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PREFACE 


This manual describes the facilities available to a programmer 
implementing an application in an OS/32 real-time or 08/32 
multi-terminal monitor (MTM) environment. Chapter 1 introduces 
the fundamental environmental concepts of the system. Chapters 
2, 3, 4 and 5 give specific details of the data structures and 
programming methods used to access 0OS/32 system services. 
Included in these chapters are descriptions of task structure, 
trap handling, file management services and the OS/32 supervisor 
calls (SVCs). To aid programmers who prefer to work with 
high-level languages, programming examples are given in FORTRAN 
VII and Pascal, as well as assembly language. Full details on 
the SVCs used in these examples can be found in the 08/32 
Supervisor Call (SVC) Reference Manual. 


System programmers wishing to implement privileged software for 
writing system level control programs are referred to the O0S/32 
System Level Programmer Reference Manual. 


Revision 02 of this manual introduces background material needed 
to use the Mirror Disk facility. A list of default trap handling 


messages have been added to Chapter 3. Chapter 4 includes 
introductory information of the mirror disk feature. All task 
structures, control information and system data structures have 
been updated to reflect these revisions. Features that are 


applicable only to the Model 3200MPS System are identified as 
such. This revision is intended for use with the 0OS/32 RO7.2 
release or higher. 


For information on the contents of all Perkin-Elmer 32-bit 
manuals, see the 32-Bit Systems User Documentation Summary. 
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CHAPTER 1 
PROGRAMMING IN AN O0S/32 ENVIRONMENT 


1.1 OS/32 OPERATIONAL OVERVIEW 


The Perkin-Elmer OS/32 operating system (OS) is designed to 
facilitate programming in a real-time environment. Whether a 
task is to collect data from a transducer, maintain inventory or 
process seismic data, OS/32 provides software service routines 


that can save programming time and effort. These services 
include program execution scheduling, memory management, file 
management, fault handling, device-dependent and 


device-independent input/output (I/0) services, and intertask 
communication and control. 


How OS/32 actually implements these services depends on the 
environment within which a program is executed. OS/32 provides 
three types of operating environments for application programs: 


e Real-time 
e Time-sharing 


@e Transaction processing 


All three environments can exist simultaneously on the same 
Perkin-Elmer 32-bit processor. — 


The OS/32 real-time operating environment is an event-driven, 
priority-based, multitasking environment in which the other 
operating environments) exist as monitors. Monitors are 
specialized real-time systems that manipulate the real-time 
scheduling components of OS/32 to create an environment that uses 
higher level scheduling algorithms. OS/32 is augmented for 
time-sharing by the 0S/32 Multi-Terminal Monitor (MTM) . 
Transaction processing is provided by RELIANCE. Features of the 
OS/32 operating environments are summarized in Figure 1-1. 


This manual deals exclusively with the real-time and time-sharing 


environments. For more information on transaction processing, 
see the RELIANCE Overview Manual. 
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6025-2 


OPERATIONAL 
ENVIRONMENTS 


@ REAL-TIME 
e@ TIME-SHARING (MTM) 
@ TRANSACTION PROCESSING (RELIANCE) 


USER 
INTERFACE 


REAL-TIME 
FEATURES 


0S/32 TERMINAL COMMAND LANGUAGE 
OS/32 SUPERVISOR CALLS (SVCs) 
OS/32 SYSTEM MACRO LIBRARY 
FORTRAN Vil RUN-TIME LIBRARY (RTL) 
PASCAL PREFIX 


@ CAPACITY 
— 255 TASKS (252 USER-WRITTEN TASKS) 
— 255 PRIORITY LEVELS 
e INTERTASK COMMUNICATION AND CONTROL 
FACILITIES THAT ALLOW A TASK TO 
— SEND MESSAGES TO OTHER TASKS 
— LOAD TASKS WITHMWITHOUT INTERTASK 
CONTROL FACILITIES 
— SUSPEND EXECUTION OF A TASK 
— RELEASE A TASK FROM SUSPENSION 
— CHANGE PRIORITY OF ANOTHER TASK 
— START EXECUTION OF A TASK IMMEDIATELY 
OR AFTER A SPECIFIED TIME PERIOD 
— ROLLA TASK TO DISK AFTER EXECUTION 
@ MULTIPROCESSOR CONTROL FACILITIES THAT 
ALLOW A TASK TO 
— CONTROL AUXILIARY PROCESSORS 
— DIRECT TASKS TO AUXILIARY PROCESSORS 
— PERFORM TRANSPARENT LOAD-LEVELLING 
e PROTECTION FACILITIES 
— INTERNAL FAULT MANAGEMENT 
— INTERTASK MEMORY PROTECTION 
— PASSWORK-BASED SECURITY 
e INPUT AND OUTPUT SPOOLING 


e@eee8e 


TIME-SHARING 
FEATURES 


CAPACITY 

— UP TO 65.536 SHARABLE USER ACCOUNTS 

— UP TO 64 ONLINE USERS 

~- ANY MIX OF INTERACTIVE OR BATCH 
PROGRAMS 

— DIAL-IN SUPPORT 

FACILITIES 


— MTM TERMINAL COMMAND LANGUAGE 
— PROGRAM DEVELOPMENT COMMANDS 
— PRIVATE, GROUP, AND SYSTEM FILES 
— DOCUMENT PREPARATION AIOS 
— SYSTEM AND USER ACCOUNTING 
e VIRTUAL TASK MANAGER (VTM) 
— PROVIDES VIRTUAL MEMORY ON 
MEMORY ADDRESS TRANSLATOR 
(MAT) PROCESSORS 
— SUPPORTS MULTIPLE TASKS UP TO 16MB 
— DESIGNED FOR LARGE TASKS 
— NO IMPACT ON OTHER TASKS IN SYSTEM 


PROGRAM 
DEVELOPMENT 


ANY MIX OF LANGUAGES 
— FORTRAN VII 
COBOL 
COMMON ASSEMBLY LANGUAGE (CAL/32) 
PASCAL 
BASIC 
CORAL 66 
RPG 
PROGRAM PREPARATION AIDS (EDIT, SCREEN 
EDITOR, COPY) 
PROGRAM DEVELOPMENT AIDS (LINK, OS/32 
AIDS, DEBUG/32) 


TRANSACTION 
PROCESSING 
FEATURES 


e OPERATES CONCURRENTLY WITH TIME-SHARING 
AND/OR REAL-TIME APPLICATIONS 


e DATA MANAGEMENT 
e SUPPORTS COBOL OR FORTRAN PROGRAMMING 


Figure 1-1 Summary of OS/32 Features 
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1.2. OS/32 REAL-TIME ENVIRONMENT 


OS/32 real-time operations enhance the hardware facilities 
provided by a Perkin-Elmer computer. As a multitasking system, 
OS/32 can support up to 252 user-written programs executing 
concurrently. One of these programs can run as a background 
program while the others are executing in the foreground. 


OS/32 uses a priority~-driven scheduling algorithm with up to 255 
priority levels to decide when and how long each program should 
execute. Priorities are scheduled so that transient events 
monitored by a real-time program are captured and evaluated 
quickly, and so that all system peripherals are used effectively. 


OS/32 also includes a timer facility that can be used to control 
the start of a procedure or detect whether a procedure has 
overrun its course. Other control services allow a program to 
reassign the priority of itself or another executing program. 


When internal fault conditions (such as arithmetic overflow, 
power restore or incorrect data formats) are detected by the 
processor, the currently executing program is suspended and 
control is returned to the OS. OS/32 handles these traps through 
default system trap handling routines. Other services are 
provided, however, that allow application programs to _ provide 
customized trap-handling routines for handling their own fault 
conditions. 


As the need to access larger programs and data bases increases, 
the memory addressing capability of a system will have a greater 
effect on performance. The 32-bit architecture of OS/32 provides 
a memory addressing capability of up to 16Mb for each of the 255 
programs running on the system. 


OS/32 provides both device-dependent and device-independent I/O 
services. By using device-independent services to perform [I/O 
transfers, devices can be reconfigured without reprogramming the 
application. Dev ice-dependent I/O allows control of 
device-specific functions such as density select on magnetic 
tape, screen access on a block mode terminal, or 
connect/disconnect on a dial-up line. 


OS/32 also supports user-transparent queuing of I/O requests to 
files and devices. Each time an I/O transfer is completed, 0OS/32 
activates any outstanding eligible I/O requests before returning 
control to the executing program. 


48-039 FOO RO2 13 


In a real-time environment, central processing unit (CPU) idling 
can be critical. The spooling utilities available with 0S/32 
help eliminate the CPU idling that can occur when writing to slow 
devices. When a spooler is used, all output is assigned to a 
pseudo device rather than an actual physical device. A spooler 
redirects this output to files on disk. Later, the spooler 
writes these files to the correct physical device on a priority 
basis. OS/32 provides two spoolers: SPL/32, a flexible, dynamic 
program designed to meet the high volume of printing required by 
the commercial user; and OS/32 Spooler, a smaller program for 
users with fewer printers and less memory. See the SPL/32 System 
Administration Reference Manual and OS/32 Multi-Terminal Monitor 
(MTM) Reference Manual for more information on spooling in an 
OS/32 environment. 


OS/32 file management services provide five different file types: 
indexed, nonbuffered indexed, contiguous, extendable contiguous, 
and long record files. Each file type is designed to meet the 
requirements of specific real-time situations. For example, 
nonbuffered indexed and extendable contiguous files are designed 
for applications that involve random I/O and require variable 
length files that can be extended without system buffering 
overhead. Applications that require a fixed-file length and no 
buffering overhead can use the contiguous file type. Long record 
files are designed for applications that require large record 
lengths. For applications that involve sequential I/O (such as 
compiling a program), the indexed file type is preferred. 


In order to operate smoothly, a multitasking system should allow 
communication among executing programs. OS/32 provides a queue 
message service that gives each program its own private message 
queue consisting of a chain or ring of message buffers. Two 
types of message services are provided. One type passes 
fixed-length (64-byte) messages. The other type allows variable 
length messages with no limit on the message length other than 
the amount of memory available to the task. 


1.3 OS/32 MULTI-TERMINAL MONITOR (MTM) TIME-SHARING ENVIRONMENT 


OS/32 MTM adds another dimension to the OS /32 real-time 
facilities. This dimension is time-sharing. Under MTM, up to 64 
users can be simultaneously signed on to a Perkin-Elmer system in 
any combination of interactive or batch modes. To prevent one 
user from tying up the CPU to the exclusion of others’ signed on 
the system, MTM schedules processor time according to the jobs 
performed by the programs. Compute-intensive jobs are given 
lower priority but longer time-slices, and I/O-intensive jobs are 
given higher priority levels and shorter time-slices. 


Link, the OS/32 linkage editor, supports the virtual task manager 
(VTM) . VIM provides a virtual memory capability on a 
task-by-task basis. This capability allows tasks consisting of 
up to 16Mb of code and data to execute in as little as 128kb of 
memory. See the OS/32 Link Reference Manual for more information 
on VTM. 
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The priority scheduling mechanism (PSM) dynamically alters MTM 
task priority. PSM increases system throughput by adjusting the 
priorities of MTM subtasks according to their run-time behavior. 
PSM performs a periodic check on the run-time behavior of all MTM 
subtasks. Based on this behavioral information, PSM adjusts the 
priorities of subtasks whose initial load priorities have been 
assigned. 


For further information on PSM, see the Multi-Terminal Monitor 
(MTM) System Planning and Operator Reference Manual. 


One of the main uses of the time-sharing environment is program 
development. MTM users can develop programs in Common Assembly 
Language (CAIL/32), FORTRAN VII, Pascal, COBOL, BASIC, CORAL 66, 
RPG, or ‘'C'. The MTM terminal command language allows users to 
develop their own command files for compiling, assembling, 
linking and running a _ program. See the OS/32 Multi-Terminal 
Monitor (MTM) Reference Manual for more information on developing 
programs in an MTM environment. 


To support a diverse community of users, Perkin-Elmer provides 
system operators and/or system administrators with the Authorized 
User Utility. This utility allows certain privileges for each of 
the 64K (65,536) accounts supported on the system. Once 
privileges have been specified for an account, all users”) signed 
on that account receive those privileges. For information on 
what privileges can be assigned, see the OS/32 Multi-Terminal 
Monitor (MTM) System Planning and Operator Reference Manual. 


Because MTM operates as a monitor within the OS/32 real-time 
environment, MTM can serve as a low-priority background 
environment for real-time applications or the primary environment 
in the system. 


1.4 THE OS/32 APPLICATION PROGRAMMER 


An application programmer is responsible for writing programs 
that result in optimum system response and throughput for a 
particular application. By using the OS/32 software services 
described in this manual, the user can greatly reduce the 
programming effort needed to achieve greater performance. The 
following chapters describe the basic data structures that should 
be understood to use 0S/32 system services effectively. 
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CHAPTER 2 
TASK STRUCTURE AND EXECUTION CONTROL 


2.1 INTRODUCTION 


When a program is compiled or assembled, it is converted into 
object modules that are stored in one or more object files on 
disk. These object modules must be converted into an executable 
form before the program can be run. This executable form is 
called a task. 


As shown in Figure 2-1, the OS/32 linkage editor, Link, performs 
this conversion by creating an image of the task from the modules 
in the object files. Link stores the task image, with 
instructions for loading the task, in an image file on disk. 


OBJECT 
LIBRARY 


5612 


OBJECT 
MODULE #1 


OBJECT 
MODULE #2 


Sine 
—— 

Yl 
[ie 


MAIN MEMORY 


A 


OBJECT 
MODULE #n 


Figure 2-1 Conversion of Object Modules into Task Image By 
Linkage Editor 
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An application task can be linked as an executive-task (e-task), 
diagnostic task (d-task) or user task (u-task). E-tasks run with 
memory relocation/protection hardware turned off and are allowed 
to execute all instructions provided by the Perkin-Elmer 
processor hardware. D-tasks, like e-tasks, can execute all 
instructions; however, they run with the relocation/protection 
hardware enabled. U-tasks run with the _ relocation/protection 
hardware enabled and are restricted to a subset of machine 
instructions known as nonprivileged instructions. This manual 
pertains to nonprivileged u-tasks only. For more information on 
e-tasks, d-tasks and privileged u-tasks, see the 0OS/32 System 
Level Programmer Reference Manual. 


The following sections describe the format of the image file for 
a u-task, how a u-task is actually loaded from this file into 
memory, and what happens to a task after it is loaded. These 
sections also refer to a number of Link and OS/32 operator 
commands that are used by the programmer to develop programs. To 
learn more about the commands discussed in these sections, see 
the OS/32 Link Reference Manual or OS/32 Operator Reference 
Manual. 


2.2 IMAGE FILE FORMAT 


Figure 2-2 shows the format of an image file for a_ task. The 
first section of the task image file is the loader information 
block (LIB). The LIB tells the OS/32 loader how to load the 
image into memory. While the task is loaded, the LIB is kept in 
the loader's private memory area, not in the task address’ space, 
until the loader no longer requires it. 


Following the LIB is the history records area. The history 
records are created by 0OS/32 Patch. Patch is a utility that 
allows the user to update a program by making changes to its 
image or object file instead of the source. Any changes made to 
the task or its LIB via Patch are recorded in the history records 
area. See the OS/32 Patch Reference Manual for more information. 


Following the LIB and the history records, if they exist, is the 
task image that is actually loaded into memory. This task image 
consists of at least one private image segment. The linkage 
editor creates the private image with read, write and execute 
privileges. The private image contains the impure code from the 
included object modules. Impure code is code that cannot be 
shared by other executing tasks. It can consist of the user 
program code, data that the user designates as impure, and common 
data areas such as those used by the FORTRAN COMMON statement to 
store variables. If NSEGMENTED is specified as a task option in 
the [.ink OPTION command when the task is built, the pure code is 
also included in the private image. 
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LOADER 
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BLOCK (LIB) 
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ROOT 
PRIVATE IMAGE 
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SHARED 
IMAGE 
SYMBOLIC 
DEBUG 
DATA 
FOr 


Figure 2-2 Task Image File Format for a Segmented Task 
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Each user who loads the task is provided with a copy of the 
private image. The first segment of the private image is known 
as the root’ segment. The root contains the primary task 
workspace, the impure code, the user-dedicated location (UDL), 
and if the task is nonsegmented, the pure code. In addition, any 
absolute code found in the object modules is located in the root. 


The UDI. is used to communicate between the user task and the 
operating system. Within the UDL is the task status word (TSW). 
Each task has an active TSW that defines the enabled state of 
task interrupts and task queue entries as well as the current 
program location (see Chapter 3). The TSW should not be confused 
with the program status word (PSW). The TSW is a convention of 
an OS/32 task, while the PSW is a convention of a processor. 


If a task is to use overlays (i.e., after the task is loaded, 
certain subroutines, or overlays, are to remain in the image file 
and be fetched into the root as needed), they are formatted in 
the private image overlay area following the root. Link is 
instructed to construct overlays through the OVERLAY command. 


The overlay descriptor table (ODT) following the overlay area 
contains instructions that tell the loader when to load the 
overlays into memory. The ODT is loaded into the task control 
block (TCB) after the task is loaded. In a multitasking system, 
each loaded t.ask is assigned a TCB in dynamic system space. All 
task status information is stored in the TCB during task 
execution. 


If the task is segmented, all pure code from the object modules 
is placed in the shared image segment of the image file. This 
area has only read and execute access privileges. When the first 
copy of the segmented task is loaded into memory, both a private 
and a shared image segment are created. If more than one user 
loads the task concurrently, each user is given a copy of the 
private image, but they all share the first copy of the shared 
image. Hence, only one copy of the shared image remains in 
memory during multiple simultaneous executions of the task. 


If the task is to be debugged using the Perkin-Elmer Symbolic 
Debugger (DEBUG/32), Link places task data required by the 
debugger following the shared image segment. This data remains 
in the image file during task execution so that it is always 
available for use by the debugger. 


A task may require access to subroutines or data areas in 
addition to those created by the programmer and contained in the 
task's object modules. OS/32 supports two types of external code 
and data. One type is an object module such as the FORTRAN or 
Pascal run-time library (RTL). Routines in object libraries are 
included in a task's root segment or shared segment using the 
Link LIBRARY command. 
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The other type of external code or data is called a partial 
image. A partial image may consist of code (e.g., an RTL 
routine) or data (e.g., a shared common block). Partial images 
are built by separate runs of the il1inkage editor, and each 
partial image exists in its own image file. A partial image is 
included in a task's address space by the Link RESOLVE command. 
In addition, an uninitialized shared common image can be created 
in memory either by the TCOM command at system generation 
(sysgen) or by the OS/32 operator TCOM command. 


2.3 LOADING A USER TASK (U-TASK:) INTO MEMORY 


In a multitasking system, u-tasks loaded into memory must _ be 
prevented from executing code in common data areas as well as any 
of the privileged instructions designated for the exclusive use 
of the operating system (OS); e.g., input/output (1/0) and 
processor state change instructions. Likewise, a u-task needs 
protection from other tasks that might attempt to interfere with 
its execution. The relocation/protection hardware provides this 
protection. 


Perkin-Elmer processors use one of two types of 
relocation/protection hardware. The Model 7/32, 8/32 and 3220 
processors use the memory access controller (MAC); the Model 


3205, 3210, 3230, 3240, 3250 and 3200MPS processors use the 
memory address translator (MAT). 


When a u-task is loaded into memory, the _ relocation/protection 
hardware automatically allocates the first relative address in 
the task's root segment to the task's first physical address’ in 


memory. To the programmer, the task appears to be loaded at 
location O in memory. Actually, the MAC or MAT maps a range of 
task logical addresses into the available physical memory 


addresses. Thus, any program address referred to during program 
execution is translated and relocated to the correct physical 
address before memory is accessed. 


The range of addresses mapped for each task make up the u-task 


logical address space. Figures 2-3 and 2-4 show how the 
Perkin-Elmer relocation/protection hardware maps' the u-task 
address space into segments. As shown in Figure 2-3, each 


segment mapped by MAC starts on a 256-byte boundary. Up to a 
maximum of sixteen 64kb segments are allocated by MAC for each 
task, providing a maximum task address space of I1Mb. Each 
segment is further divided into 256 pages. A page is a set of 
256 contiguous one-byte locations beginning on an even 256-byte 
boundary. MAC locates the first address of each segment of the 
task on a 256-byte boundary; e.g., 00000, 10000, up to FOOOO. 
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Fach MAC segment consists of two-hundred fifty-six 256-byte pages 
or 64kb. 


Figure 2-3 Task Address Space on a MAC Machine 
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Each MAT segment consists of thirty-two 2,048-byte pages or 64kb. 


Figure 2-4 Task Address Space on a MAT Machine 
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Figure 2-4 illustrates how MAT describes the u-task address 
space. On MAT machines, a maximum of two-hundred fifty-six 64kb 
segments or 16Mb are available for each u-task. On all MAT 
machines except the Model 3205, each segment is divided into 
thirty-two 2,048-byte pages. On the Model 3205, each segment is 
divided into sixteen 4096-byte pages. MAT locates the first 
address of each segment of the task on a 2,048-byte or 4,096-byte 
boundary. 


As described in Section 2.2, a task may reference partial images 
resolved when the task is link-edited. Based on information 
recorded by Link in the LIB, the loader will ensure that the 
required partial images are in memory and automatically load any 
that are not. The partial images are then mapped into’ the 
appropriate ranges of the task's logical address space. 


If the image is formatted as a segmented task, the task is loaded 
into its address space as two distinct (possibly discontiguous) 
areas, private and shared, as shown in Figure 2-5. Every task 
has a private area. This area contains the private image code 
(UDL, root, plus any overlay areas required by the task). The 
relocation/protection hardware starts loading this code at the 
beginning of segment O in the task address space. 


The relative task address of the first fullword of the private 
area is called UBOT. For u-tasks, UBOT is always 0. Starting at 
UBOT, the loader loads the UDL into the first 256 bytes of 
segment 0. Following the UDL is the root node, which consists of 
segments that hold the user program code that cannot be shared by 
other tasks in the system. 


If a task is to be executed using overlays, segments mapped out 
for these overlays are placed sequentially above the root. Above 
the overlays, the loader reserves a workspace area for the task. 
For example, some tasks require workspace to build and store 
symbol tables during execution. The amount of workspace that is 
reserved for a task is determined by the workspace parameters 
given in the OPTION WORK command when the task is built. These 
parameters are the nominal space and the maximum work space. 
UTOP is a pointer to the address of the first byte of the task 
workspace. UTOP plus the nominal workspace is equivalent to 
CTOP, the pointer to the address of the last addressable halfword 
in the task workspace. CTOP must be equal to or less than the 
maximum workspace parameter of the OPTION WORK command. 


The pure code of a segmented task is loaded into the segments 
directly above the reserved task workspace. As noted in Section 
2.2, if two or more users load the task concurrently, the copy of 
the shared segment loaded into memory for the first task is 
mapped into the logical address space of each of the later tasks. 
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Figure 2-5 Segmented Task Loaded into Memory 
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2.4 TASK STATES AND PRIORITIES 


In a multitasking system, the task scheduler enforces’ the 
scheduling algorithm that determines which loaded task should be 
executed next. Tasks are scheduled according to the level of 
priority assigned to them. The OS/32 task scheduler can 
accommodate 255 levels of task priorities ranging from 1 to 255, 
with priority 1 being the most favored. Several tasks can exist 
at the same priority level. 


An executing task is said to be in the current state. Other 
tasks that have been started, but are lower in priority than the 
executing task, are in the ready state. The task scheduler 


initiates execution of the highest priority ready task. 


If the executing task becomes suspended, (either by the OS, the 
operator or another task), the task is said to be in the wait 
state. For example, a task becomes suspended when it requests a 
service from the OS, such as an I/O transfer. This task remains 
in a wait state until the operation is completed, at which time 
the task enters the ready state. Table 2-1 lists the conditions 
under which a task can become suspended. 


A special wait state is the dormant state. When a task is 
loaded, it is initially in the dormant state. When a task is 
started (either by the OS/32 START command or by another task), 
the task is removed from the dormant state and placed in the 
ready state. Once a task has been started, it can only become 
dormant again if it is a resident task; i.e., if the task remains 
in memory after it reaches end of task. Because it enters the 
dormant state after execution, a resident task can be made ready 
through the OS/32 START command. 


Nonresident tasks cannot reenter the dormant state after 
execution because they are removed from memory at end of task. 
Hence, nonresident tasks must always be loaded and placed in the 
dormant state before they can be started. A task can be made 
resident or nonresident by specifying these task options in the 
OPTION command when the task is built. 


Nonresident tasks can enter the rolled. state. A task becomes 
rolled when the task scheduler writes the task's private image 
segments to disk to make room for a higher priority task. A 


rolled task enters the ready state as soon as it becomes the 
highest priority rolled task and sufficient memory is available 
to accommodate it. 


0OS/32 control of task states during and after task execution is 
illustrated in Figure 2-6. 
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TABLE 2-1 TASK WAIT STATES 
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WAIT STATE MEAN ING 
I/O wait Wait for an I/O operation to complete. 


Connection wait Wait for a system resource. 


Timer wait Wait for an interval to elapse or for a 
particular time of day to occur. 


Trap wait Wait for a task-handled trap to occur. 


Load wait Wait for a requested load operation to 
complete. 


Task wait Wait to be continued by another task. 


Roll wait Wait to be rolled out. 


Terminal wait Wait for I/O to complete toa 
terminal device (applies to terminal 
tasks only). 

I/O block wait Wait for an I/O block to be freed when task 
reaches its I/O control block limit. 


Counters overflowed; task waiting for 
accounting facility to collect accounting 
data and remove wait. 


Accounting wait 


Intercept wait Wait for a intercepted supervisor call 


(SVC) to be executed. 
Console wait Wait for system operator, user or another 
task to instruct an interrupted task to 
continue execution. 

Dormant wait Wait for system operator, user or another 
task to initiate a task. After a task is 
loaded, it enters the dormant state and 
remains there until execution is initiated. 
When a resident task goes to end of task, 
it reenters the dormant state. 
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Figure 2-6 Task States 


2.5 MONITOR TASKS AND SUBTASKS 

In addition to the OS/32 task scheduler, execution of a task can 
be controlled by another task called a monitor. Tasks that are 
placed under monitor control are called subtasks. A monitor 
creates the operating environment within which its subtasks are 
executed. For example, a monitor can: 


@ load, start, cancel or suspend any of its subtasks; 


@ override the task options that had been set when the subtasks 
were linked; or 


@e make logical unit (lu) assignments for any of its subtasks. 
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A task can become a monitor by specifying the subtask reporting 
option when loading another task. The number of subtasks that 
can be assigned to a single monitor is unlimited (within the 252 
user-written tasks supported). 


The subtask reporting option causes the OS to keep the monitor 
informed of the status of its subtasks; i.e., when the subtasks 
have been started, suspended, released, rolled out, etc. When a 
monitor goes to end of task, all of its subtasks are forced to 
end of task. 


2.5.1 The OS/32 Multi-Terminal Monitor (MTM) 


All tasks loaded and started in an OS/32 time-sharing environment 
execute as subtasks of MTM. MIM subtasks run at a maximum 
priority of at least one less than the priority of MTM; i.e., if 
MTM's priority is 140, the task's highest priority could not 
exceed 141. 


Both interactive and batch processing are supported by MT. Up 
to 64 interactive tasks can be executed concurrently, one from 
each MTM terminal. The number of batch jobs that can execute 
concurrently is determined by the operator during MTM system 
start-up and is a maximum of 64 minus the number of interactive 
terminals. Any batch jobs submitted above this number are queued 
by MTM. See the OS/32 Multi-Terminal Monitor (MTM) Reference 
Manual for more information on MTM. 


2.6 RESTRICTIONS ON INTERTASK COMMUNICATION 
OS/32 places some restrictions on which tasks can communicate 
with one another by assigning a group ID to each task. Normally, 


a task can communicate only with tasks within its assigned group. 


Group IDs are assigned according to the operating environment 


under which a task is loaded. Tasks loaded into an 0OS/32 
real-time environment are divided into two groups: foreground 
and background. A monitor and its subtasks are assigned to their 
own group. System tasks (the console monitor, the command 


processor, MTM and the spooler) are in a separate group called 
the systems group. 


To communicate with tasks outside its group, a foreground task 
should be link-edited with the UNIVERSAL task option enabled. 
0OS/32 defines a background task as nonuniversal to prevent it 
from communicating with tasks outside its group. 
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A task monitor determines whether any of its subtasks' can 
communicate outside the monitor's group. For example, all MTM 
subtasks are loaded with the communication task options specified 
for their accounts via the authorized user file (AUF), regardless 
of the task options chosen when the subtasks were built. See the 
OS/32 Multi-Terminal Monitor (MTM) System Planning and 
Configuration Guide for information on MTM sysgen options and the 
specification of options for MTM accounts. 


2.7 ACCESSING OS/32 SYSTEM SERVICES 


A u-task can access all of the nonprivileged system services that 
are available through 0S/32. Tasks communicate with the OS 
through structures that the task builds within its task address 
space. OS/32 uses the information stored in these structures to 
perform the services requested by the task. 


One structure that is of particular importance in a_ real-time 


environment is the UDL. Chapter 3 examines the UDL and its use 
in handling program interrupts. 
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CHAPTER 3 
INTERRUPT SERVICING IN A REAL-TIME ENVIRONMENT 


3.1 INTRODUCTION 


Real-time application systems are often designed to _ interrupt 
task execution when certain events occur. For example, if 
program output was invalidated when execution of an instruction 
caused a floating point overflow condition, the programmer would 
want to know when such an event occurred. Otherwise, the 
programmer could not be certain that the results of a program 
were valid. The mechanism that informs the task when such an 
event occurs is called a task trap. 


Traps suspend task execution at the location following the 
instruction that was executing when a trap-causing event 
occurred. Execution then continues in the routine that will 
handle the trap. The location counter (LOC) at the time of the 
trap is saved in the user-dedicated location (UDL) so that the 
interrupted execution can be resumed. For example, the user may 
create a trap-handling routine so that when an event like a 
floating point overflow occurs, the trap-handling routine places 
asterisks in the output of a variable and outputs some meaningful 
message. The trap routine then causes the original task to 
resume execution at the instruction following the one that caused 
the suspended trap execution. 


Task execution can be resumed only if the state of the task was 
saved by the operating system (OS) prior to executing the trap 
service routine. The task structure that contains the 
information to be saved by the OS is the task status word (TSW). 
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3.2 TASK STATUS WORD (TSW) 


The structure of the TSW is shown in Figure 3-1. 
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BITS 012 3 4 5 6 7 8 14 15 16 17 18 19 20 21 22 23 24 26 27 28 31 


LOC 


BITS 32 39 40 63 


Figure 3-1 Task Status Word 


As shown in Figure 3-1, the TSW occupies eight bytes aligned on 
doubleword boundaries. The first 28 bits of the TSW are used to 
enable or disable task traps for certain conditions. For 
example, if bit 2 is set, a task trap will occur when execution 
of an instruction results in an arithmetic fault. 


The current condition code of the task is saved in the area 
comprised of bits 28 through 31. The program LOC is contained in 
the area following bit 39. All TSW bit settings and their 
corresponding effects on task execution are listed in Table 3-1. 


When a task is link-edited, using OS/32 Link, its TSW is 
initialized. The default TSW has all task traps disabled and the 
task's starting address in the LOC field. The user can change 
the TSW trap and LOC default values initialized by Link by 
specifying the desired bit settings in the Link OPTION TSW 
command. See the OS/32 Link Reference Manual for more 
information on this command. 


The initialized TSW is placed in an OS data structure called the 
task control block (TCB) when the task is loaded into memory. If 
a task trap bit is disabled, that trap-causing event will be 
handled by the default OS/32 trap-handling routine. See Section 
i ae 


If the trap bit for one of the internal fault conditions is 
enabled, execution control is transferred to the user-written 
trap-handling routine, as described in Section 3.5. 
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TABLE 3-1 


ee ee nem ees Se me meme me mS mee Ok es ee erm ee eres meee mers meee ee ms ms re me ee we ree ee es ne lee me ee ee ee Ge ewe mee ome Ree ee ee me 


TSW.DIQM 


Enable Power 
Restore Trap 


Enable 
Arithmetic 
Fault Trap 


Enable 
Enable 


Queue 
Service Trap 


Task 


Enable 
Memory 
Access Fault 
Trap 


Enable 
Illegal 
Instruction 
Trap 


Enable Data/ 
Alignment 
Fault Trap 


Queue Entry 
on Subtask 
Change 


Queue Entry 
on Device 
Interrupt 


TSW BIT 


ere ee ee re dere come eee coms memes mes ere cm GS cure ees rem mer nee mens ese cme es met es mee crm mm me mee mer. ees cee me ms ee ee ee eee eee ee em 


SETTINGS 


ee ee ee ee ee de ee ee Oe ee ee ee oe 2 ee oe ee ee ee ee ee ee ee ee ee ee ee ee ee 
=——— ee a Ne Se a a a 


Suspends execution until 
a trap occurs. 
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Notifies task when power 
is restored after a 
power failure. 
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Notifies task when an 
arithmetic fault occurs. 
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Notifies task when an 
SVC14 is issued. 
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Notifies task when an 
item is placed on the 
task queue. 
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Notifies task when it 
attempts to access 
memory outside its task 
address space. 
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Notifies task when it 
attempts to execute 
an illegal instruction. 
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Notifies task when it 
attempts to execute an 
instruction that causes 
a data format or 
alignment fault. 


Prevents scheduling task 
to APU execution queue. 
Applies to Model] 3200MPS 
System only. 
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Notifies task of subtask 
state change by adding a 
3-fullword entry to task 
queue. 
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Notifies task of a de- 
vice interrupt by adding 
a fullword entry to the 
task queue. 
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TABLE 3-1 TSW BIT SETTINGS (Continued) 
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TABLE 3-1 TSW BIT SETTINGS (Continued) 
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mo ney ee eter me ee me my SE came ee Sem mee ame meee mee See) mimes meee Se eee cere mm SY rue ces mune Meme tees eee en UD wwe meme nme SOR See were meen cm em eee ee eee em Se es em mee te ss tem eee Oe me mene ier ee ee one 


3.3 TRAPS HANDLED BY OS/32 

Internal trap-causing events detected by the processor hardware 
are called faults. Five types of faults can be detected by the 
processor: 

@ Power restoration after power failure 

e@e Arithmetic faults (see Table 3-4) 

@ Memory access faults (see Table 3-6) 

e Illegal instruction faults 

e Data format/alignment faults (see Table 3-5) 

When a fault is detected by the processor, the currently 
executing task is checked for trap fault-handling facilities. If 
none exist (TSW trap bits are zero), the task is suspended and 


control is given to the appropriate default system trap-handling 
routine. 


48-039 FOO RO2 335 


——_ eee 


ee 


a eee eee ee 


In the case of power restoration, the default 05/32 trap-handling 
routine causes suspension of task execution until the task is 
continued or cancelled by the operator. When an arithmetic, 
memory access, illegal instruction or data format/alignment fault 
occurs, the default O0S/32 trap-handling routine identifies the 
fault and outputs a message to the console. Task execution is 
then suspended. 


All fault-caused traps are handled in the above manner, except 

arithmetic faults. Arithmetic faults are handled based on the 

following three possible conditions: 

e 0OS/32 task arithmetic fault pause option (AFPAUSE) 

e TSW arithmetic fault bit (bit 2) 

e Hardware floating point underflow interrupt bit (bit 19) of 
the PSW (the AF bit on Model 7/32 and 8/32 Systems) 


The task option for arithmetic fault handling is set at Link time 
via the Link command: 


OPTION AF PAUSE 
NAF PAUSE 


or at run-time via the OS command: 


OPTION AF PAUSE 
AF CONT 


The TSW fault bit is set as described in Section 3.6, and a PSW 
bit is set or reset by SVC2 code 4. See the 05/32 Supervisor 
Call (SVC) Reference Manual. The results are described in Table 
3-2. 
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TABLE 3-2 ARITHMETIC FAULT HANDLING 


ee es 


HARDWARE =; LINK/OS H 
PSW BIT 19 {| TASK OPTION {| BIT 2 


0 


TSW 
ACTION 

For Model 7/32 and 8/32 pro- 

cessors, all AF fault recog- 

nition disabled; task con- 

tinues; no OS message. 


X X 


For Perkin-Elmer Series 3200 
processors, floating point 
underflow recognition dis- 
abled; task continues; no OS 
message. 


ee ee ee es ee ee eee ee 


H 0 | OS message sent to console; 
i } task continues. 


0 Ce DS ae aD SOR SED See ces Gee come wee mee come ES ee ee ee eee eee Gem: meee ons uD ue ems come ie ee oie coe ee ee ee eee ee oe ee eee ee Se me ee ee ne em ee ce ee ee ee ee ee ts eis ce eee ee ee ee oe ee 


0 | OS message sent to console; 
| task is paused. 


H Continue |] 1 | No OS message sent to console; 
| task trapped to AF handler. 


| OS message sent to console; 
| task is paused. 


how 


Interrupt enabled 
Interrupt disabled 
Don't-care 


The following are the default trap-handling messages sent to the 
system console or MTM terminals. 


Error Messages: 


taskid: ACCESS PRIVILEGE ADDRESS ERROR AT RRxxxx (yyyyyy) 


The user program tried to perform a function (execute, 
store or load) that is prevented by the access privileges 
requested at Link time for the segment. The most common 
cause of this error is an attempt to store data into a 
pure, nonwritable segment. Program address is RRxxxx; 
segmentation number register is RR; physical address is 
YYYYYY- 
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taskid: ALIGNMENT FAULT INSTRUCTION AT xxxxxx (yyyyyy) 
MEMORY FAULT ADDRESS=xxxxxx (yyyyyy) 


Data instruction is not properly aligned to specific 
fields for fullword or halfword alignment. The memory 
fault address is the memory location that is not properly 
aligned. The memory fault address is given only on 
Perkin-Elmer Series 3200 machines. Program address is 
XXXXXX; physical address is yyyyyy. 

taskid: ARITHMETIC FAULT AT xxxxx (yyyyyy) 
Arithmetic fault is detected at location xxxxx in the 
taskid address space; physical address is yyyyyy. 

taskid: ILLEGAL INSTRUCTION AT xxxxx (yyyyyy) .- 
Tllegal instruction fault detected at location xxxxx in 
the taskid address space; physical address is yyyyyy. 

taskid: INVALID SEGMENT ADDRESS ERROR AT xxxxx (yyyyy) 
The task tried to address a segment outside the address 
space of the program. Program address is xxxxx; physical 
address is yyyyy. 

taskid: MEMORY PARITY ERROR AT xxxxx (yyYYyyy) 


Parity or an error correction code (ECC) machine 
malfunction is detected at location xxxxx; physical 
address is yyyyyy. 

taskid: SEGMENT LIMIT ADDRESS ERROR AT RRxXxxx (yyyyyy) 


The task attempted to access an address outside allowable 


limits for one of its segments. Program address is 
RRxxXxxX; segmentation register is RR; physical address is 
YYYYYY - 


taskid: TASK PAUSED 
Task taskid paused; results from a SVC2 code 1, operator 


PAUSE command or power fail recovery via the 0S/32 
default. 


POWER RESTORE - RESET PERIPHERALS 


Power fail restore sequence; no operator response 
required. 
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POWER RESTORE - RESET PERIPHERALS AND ENTER GO 


Power fail restore sequence; perform any manual 
intervention required at the peripheral device(s), then 
type GO (CR) to complete power recovery. 


NOTE 


Tasks that handle arithmetic fault traps 
must be link-edited with the NAFPAUSE 
task option. When an arithmetic fault 
trap occurs, NAFPAUSE prevents 0OS/32 from 
pausing the task _ so that execution 
continues with the user-wr itten 
trap-handling routine. See Section 3.5 
or the OS/32 Link Reference Manual for 
more information. 


3.4 USER-DEDICATED LOCATION (UDL) AND TASK STATUS WORD (TSW) 
SWAP 


A task that services traps requires a data structure that can be 
used to save the current TSW after a trap occurs. The OS/32 data 
structure that is reserved for this purpose is the UDL. The UDL 
is an area occupying locations O through 255 (X'FF') in each task 


impure memory space preceding the task code. Expansion of the 
$UDL macro generates the structures and equates for the UDL data 
structure. Figure 3-2 illustrates the UDL structure. The UDL 


fields used to handle traps are described in Table 3-3. 
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wa Oe a ee ee ee ee ae a 


wa 


om et ee ee ee ee ee ae 


5921-2 0 (00) CTOP (UDL.CTOP) 


4 (04) UTOP (UDL.UTOP) 

8 (08) UBOT (UDL.UBOT) 

12 (OC) DATA MANAGEMENT SYSTEM (UDL.DMS) 
16 (10) A (TASK QUEUE) (UDL.TSKQ) 

20 (14) A (SEND DATA FREE BUFFER QUEUE) (UDL.SDQ) 
24 (18) A (MESSAGE RING) (UDL.MSGR) 

28 (1C) A(SVC 14 ARG) (UDL. SV14) 

32 (20) RESERVED (UDL.EXT1) 

36 (24) RESERVED (UDL.EXT2) 

40 (28) LOAD MULTIPLE STARTING ADDRESS (UDL.LMSA) 
44 (2C) . RESERVED 


48 (30) POWER RESTORATION OLD TSW 
52 (34) (UDL.PWRO) 
56 (38) POWER RESTORATION NEW TSW 
60 (3C) (UDL.PWRN) 


64 (40) ARITHMETIC FAULT OLD TSW 
68 (44) (UDL.ARFO) 
72 = (48) ARITHMETIC FAULT NEW TSW 
76 (4C) (UDL.ARFN) 
RESERVED] 81(51) DATA FORMAT 82(52) MAC/MAT FAULT 83(53) ARITH FAULT 
80_(50) meas0N CODE (UOLARER) 


84 (54) ARITHMETIC FAULT, NEXT INSTRUCTION ADDRESS (UDL.ARFX) 


88 (58) DATA/ALIGNMENT, ACTUAL FAULT ADDRESS (UDL.DFFX) 
92_(5C) MAC/MAT FAULT, ACTUAL FAULT ADDRESS (UDL.MAFL) 
96 (60) SVC 14 OLD TSW 

100 (64) _ (UDL.S140) 

104 (68) SVC 14 NEW TSW 

108 (6C) (UDL.S14N) 

112 (70) TASK QUEUE SERVICE OLD TSW 
116 (74) (UDL.TSKO) 

120 (78) TASK QUEUE SERVICE NEW TSW 
124 (7C) (UDL.TSKN) 

128 (80) MEMORY ACCESS FAULT OLD TSW 
132 (84) (UDL.MAFO) 

136 (88) MEMORY ACCESS FAULT NEW TSW 
140 (8C) (UDL.MAFN) 

144 (90) ILLEGAL INSTRUCTION OLD TSW 
148 (94) (UDL.HITO) 

152 (98) ILLEGAL INSTRUCTION NEW TSW 
156 (9C) (UDL.INTN) 

160 (AO) DATA FORMAT FAULT OLD TSW 
164 (A4) (UDL.DFFO) 

168 (A8) DATA FORMAT FAULT NEW TSW 
172 (AC) (UDL.DFFN) 

176 (BO) 

tho (ea) RESERVED 


184 (B8) POINTER TO SYSTEM NETWORK ARCHITECTURE TABLE (UDL.SNA) 
188 (BC) SAVE AREA USED BY SYSTEM NETWORK ARCHITECTURE(UDL.RSAV) 
192 (CO) 


196 (C4) RESERVED FOR AIDS 
ae # 


OR DEBUG/32 
248 (F8) 
252 (FC) 


Figure 3-2 User-Dedicated Location 
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Note that several fields in the UDL are used to store the TSW. 
Each type of trap requires two TSW save areas, the old TSW (OTSW) 
field and the new TSW (NTSW) field. The OS uses the OTSW field 
for saving the TSW that is in the TCB when the trap occurs. The 
NTSW field is used by the task to store the TSW that contains the 
address of the user-written trap-handling routine and the new TSW 
bits to be enabled during execution of the routine. 


Unless the user specifically initializes the UDL, all locations 
in the UDL and the initial TSW are set to zero by OS/32 Link. 
Thus, for all tasks, the default is OS-handled traps. 


The users, however, can initialize the UDL by assembling the 
appropriate code and using the Link OPTION ABSOLUTE=0 command 
before including the UDL in their task or by initializing the 
fields at run-time (e.g., by calling the appropriate FORTRAN 
routines as described in Section 3.6). 


Figure 3-3 shows the effective TSW swaps to and from the TCB_ and 
the UDL. The following notes correspond to the numbers in Figure 
3=3. 


NOTES 


l. In Figure 3-3, the original TSW was 
allowed to default to zero at Link 
time. 


2. After the task is started, the TSW 
can be initialized or modified via an 
SVCc9. 


3. TSW swap is performed when the task 
trap occurs. 


4. At the end of a trap-handling 


routine, the user can return to the 
original interrupted code sequence. 
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O TASK 
INITIATION 
a a 
(2) LOAD Tsw 
(SVC9) 
INITIALIZE TSW IN TCB 
TCB 
eran a 
| oNTSW | 
@®_ task TRAP 
TSW SWAP 
BY OS 
TCB | uo_| 
OTSW 
fersw | _oTsw_| 
NTSW 
@ TRAP-HANDLING 
ROUTINE 
me | | 
NTSW 


LTSW — TSWINITIALIZED BY LINK 
OTSW — TSWINITIALIZED BY TASK WITH TASK EXECUTION ADDRESS AND TRAP BIT SET 
NTSW — TSWWITH ADDRESS OF TRAP SERVICE ROUTINE 


Figure 3-3 TSW Swap 


To perform the TSW swap, the task and the trap-handling routine 
issues a call (SVC9) to an OS/32 supervisor routine that replaces 
the current TSW in the TCB with the TSW specified as an argument 
to SVC9 (see number 2 of Figure 3-3). 


As shown in Figure 3-3, the TSW swap performed after the task is 
started replaces the link-initialized TSW in the TCB with the 
task-initialized TSW (OTSW). This swap causes task execution to 
resume at the location specified by OTSW; or, if the LOC of OTSW 
is zero, execution resumes after the SVC9 instruction. 


The TSW swap performed by the OS/32 trap mechanism, in response 
to an event, replaces the OTSW in the TCB with a copy of the NTSW 
stored in the UDL (see number 3 of Figure 3-3). Task execution 
resumes at the address of the trap-handling routine. 
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The TSW swap performed at the end of the trap-handling routine 
replaces the NTSW in the TCB with the OTSW saved in the UDL. 
Execution resumes at the instruction that was about to be 
executed when the trap occurred. See number 4 of Figure 3-3. 


In addition to the TSW swap areas, the UDL structure also 
reserves fields that are used to store information used by the 
trap-handling routine; i.e., internal fault reason codes, task 
queue address, address of message buffers, etc. 


The UDL fields that are used by a task to handle task traps are 
summarized in Table 3-3. 


TABLE 3-3 UDL FIELDS USED TO HANDLE TASK TRAPS 


CO ee ed ee 


BYTE | | MASK | | 
LOCATION j FIELD NAME H NAME i CONTENTS OF FIELD 1 
en 2 ss SSE ASME SSE | 
16('10") {| A(Task Queue) | UDL.TSKQ | Address of task queue H 


20('14') | A(Send Data Free 


UDL.SDQ | Address of free buffer queue for SVC6 
| Buffer Queue) 


i] 
4 
1 send data function | 


24('18') {| A(Message Ring) {| UDL.MSGR | Address of ring of 76-byte message buffers | 
i H {| aligned on a fullword boundary i 
a a a i a a a a a a a a a a a i a a ee ee ew ee | 
28('1C') | A(SVC14 Arg) | UDL.SV14 | Effective address of the argument to an | 
i i } svcl14 | 
ee a a a a a a ee ee ee ee H 
Second operand of Load Multiple instruc- | 

i 


40('28') | Load Multiple | UDL.LMSA } 
| Starting Address | i tion that caused a memory access fault 
i et ie ee ee ee ea ea a ee ee a a a a ee ea a ee ie ee | 
48('30') | Power Restoration {| UDL.PWRO | TSW saved by the OS/32 after a power | 
{ Old TSW | } H 


failure occurs 

ee er ee ee ere rey | 
56('38') | Power Restoration {| UDL.PWRN | TSW containing the address of the power | 
{ New TSW H } restoration trap routine to which execu- | 
| | | tion will branch when power is restored | 
i { | after a power failure occurs | 
ee ee ee we ee fr a en a a ern | 

64('40') Arithmetic Fault UDL.ARFO TSW saved by the OS/32 when an arithmetic 


Old TSW Fault trap occurs 


faulting instruction. For Model 7/32 and 
8/32 processors, LOCs point to the in- 


H 
| 
| 
For the Perkin-Elmer Series 3200 proces- | 
| 
| 
| 
struction after the faulting instruction. | 


H 
i 
i 
i 
} sors, the LOC of this TSW points to the 
‘ 
| 
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TABLE 3-3 UDL FIELDS USED TO HANDLE TASK TRAPS (Continued) 


ne ee ee re ee we es ee en we ee we we we ew ee ee ee ee ee ee ee re ee ee ee ee ee 


BYTE i { MASK j i 

LOCATION FIELD NAME H NAME H CONTENTS OF FIELD i 

SSAC SATS BSBARSESBECISAETTTETSTVSA STE STESEECCEsS SO CESSES CCSC FA STFA TCECECCEISCCKKCECECS SACS SCS SSS SES Bw SE we EE H 

72('48') | Arithmetic Fault {| UDL.ARFN ; TSW containing the address of the arith- { 

i New TSW i { metic fault trap-handling routine to which |} 

| ' | execution will branch when an arithmetic H 

H { { fault occurs H 

Ee a a a a a Pn ene Ss ene AED ER ry ON Sp ra NGA aR EN ry ee Se ee ee OEE eT) com ee Te-am, eer “es Femi Seem a { 

81('51') | Data Pormat Reason | UDL.DFFR | Reason code indicating the event that | 

| Code H | caused the data format/alignment fault i 

i ' ' (see Table 3-7) ' 

cs es? Sone co cm meh fn we elm me i, my Si ag iS: “i eS emo“ ms Sha'tar mei “p(t Sn, SS Se eis Se Ss “Ses emt H 

82('52') | MAC/MAT Fault i UDL.MAFR {| Reason code indicating the event that i 

; Reason Code { { caused the memory access fault (see { 

H ! Table 3-6) i 

i i i i 

i i { This reason code is given only for a { 

H { } memory access controller (MAC) or memory ' 

H ' } address translator (MAT) fault occurring H 

\ H } on a Perkin-Elmer Series 3200 processor. i 

ne ee ee eee ee ee ee ee we ee ce re ee eee 0 wes cee tee ee cae ee ee ee ce ee ee ee eee ee ee mn ee ee oe H 

83('53') | Arithmetic Fault } UDL.ARFR | Reason code indicating the event that ! 

+ Reason Code H | caused the arithmetic fault (see Table { 

i i i; 3-5) i 

i H H i 

i ' i This reason code is given only for an H 

i 1 | arithmetic fault occurring on a Perkin- H 

i | Elmer Series 3200 processor. { 

je me si se hc ms ce il mm es mb mi ema‘ wm Sin’ as wc scrip‘ “mm neces cs mm uhh le sin sum’ mts ante “cru eG madras nr come eee ph sa a 0 ee Set H 

84('54') | Arithmetic Fault, {| UDL.ARFX | Address of the instruction following the 1 

i Next Instruction i ! instruction that caused an arithmetic H 

; Address H { fault i 

‘ a i 4 

t 1 i ' 

{ i | This address is given only for an i 

H { | arithmetic fault occurring ona { 

{ | | Perkin-Elmer Series 3200 processor. i 

Se hee See eee eee Se eh a eS ee ee Se ' 

88('58') {| Data/Alignment, | UDL.DFFX | Address of the memory location referred to | 

i Actual Fault i | by the instruction that caused the data H 

| Address H {| format or alignment fault H 

i H H H 

i H | This address is given only for a data/ i 

i H | alignment fault occurring on a i 

i { | Perkin-Elmer Series 3200 processor. H 

eR ee a a a ae a a a a a a ee ee ee ee a H 
92('5C') MAC/MAT Fault, UDL.MAFL Address of the data or instruction that 


4 
i] 
Actual Fault { caused a memory access fault trap 
Address H 
i This address is given only for a MAC/MAT 
H fault occurring on a Perkin-Elmer Series 
1 
i 


3200 processor. 


ae ee oe oe oe oe 


3-14 48-039 FOO RO2 


TABLE 3-3 UDL FIELDS USED TO HANDLE TASK TRAPS (Continued) 


a ee ee ee en een ee ee ee ees 


Ca a ihe heii 


Ce ee ee ee ed 


TSW containing the address of the memory 


CONTENTS OF FIELD 


TSW saved by 0S/32 when an 
occurs 


SVC14 trap 


TSW containing the address of the SVC14 


trap-handling routine to which execution 


branches when an SVC14 trap occurs 


TSW saved by OS/32 when a service trap 
occurs 


TSW containing the address of the task 


queue trap-handling routine to which exe- 


cution branches when a task queue trap 
occurs 


TSW saved by 0S/32 when a memory access 
fault trap occurs 


access fault trap-handling routine to 
which execution branches when a memory 
access fault trap occurs 


TSW saved by 0OS/32 when an illegal 
instruction fault trap occurs 


TSW containing the address of the illegal 


instruction trap-handling routine to wh 
execution will branch when an illegal 
instruction fault trap occurs 


ich 


t 
! 
! 
I 
I 
! 
t 
' 
t 
t 
1 
1 
! 
| 
I 
! 
! 
i 
! 
J 
! 
! 
! 
| 
! 
| 
1 
' 
! 
! 
i 
i 
' 
t 
i 
! 
! 
t 
! 
' 
I 
' 
\ 
I 
I 
J 
' 
' 
' 
) 
i 
I 
! 
! 
t 
I 
I 
! 
! 
! 
I 
' 
I 
J 
t 
' 
J 
I 
! 
I 
! 
! 
I 
I 
' 
i 
| 
t 
t 
' 
! 
I 
' 
' 
t 
! 
t 
t 


ee ee ee ee ee ee eee ee ee ee ee a ae a a a a a eee ee ee ew we ww ww ew ew oe mee 


BYTE | H MASK 
LOCATION |} FIELD NAME H NAME 
96('60') } Svcl4 Old TSW { UDL.S140 

i] ' 

f) 4 
104('68') | SVC14 New TSW {| UDL.S14N 

t] t 

! ! 
112('70') | Task Queue Service | UDL.TSKO 

; O1d TSW { 
120('78') {| Task Queue Service | UDL.TSKN 

} New TSW } 

t t 

i} { 
128('80') | Memory Access | UDL.MAFO 

| Fault, Old TSW H 
136('88') {| Memory Access {| UDL.MAFN 

| Fault, New TSW H 

4 i 

! ! 
144('90') {| Illegal { UDL.IITO 

1 Instruction, H 

{ Old 'TSW H 
152('98') } Illegal { UDL.IITN 

} Instruction, | 

| New TSW { 

{ | 
160('AO') | Data Format Fault | UDL.DFFO 

{ Old TSW ! 

i H 

H i 

i H 

1 ! 

§ i] 
168('A8') Data Format Fault UDL.DFFN 


New TSW 


TSW saved by OS/32 when a data format or 


alignment fault trap occurs 


This TSW is saved only for a data forma 
alignment fault trap occurring on a 
Perkin-Elmer Series 3200 processor. 


TSW containing the address of the data 
format/alignment fault trap-handling 


routine to which execution branches when a 


data format or alignment fault trap 
occurs 


t/ 


oe ae ee oe oo 


mt rem mm ee am sce ey re me ee me caer ee ee eee rae ae ee ee ea ee ee ee ee ee eee ee ee ee ee wwe oe ee me we ee ee ee eee ee eee rere ee ee 
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3.5 TRAPS HANDLED BY USER-WRITTEN TASKS 


The purpose of this section is to describe and summarize the 
following task-handled traps: 


e Arithmetic faults 

e Data format/alignment faults 
e® Power restoration 

e Illegal instruction faults 

@ Memory access faults 

e Task queue service events 


e User-defined, trap-causing events 


The traps described below are divided into three categories based 
upon the causing event: hardware-based events in category 1, 
asynchronous software events in category 2, and specifically 
called (synchronous) software events in category 3. 


Before a task can handle a trap, the task must have a TSW in 
which the appropriate trap bits are set. If the trap bit in the 
TSW is enabled, execution control is transferred. to the 
user-written trap-handling routine when that fault condition 
occurs. (If the trap bit is disabled, execution control is 
transferred to the default OS/32 trap-handling routine as 
previously explained in Section 3.3.) 


Category 1 events (hardware) include arithmetic, data 
format/alignment, power restoration, illegal instruction and 
memory access faults. These events are recognized by the OS, 
which then passes control by performing a TSW swap. The TSW is 
removed from the TCB at the time of the fault and is saved in the 
UDLs at an old TSW save area. The location portion of the old 
TSW is updated to point to the next executable instruction. 


After successfully saving the old TSW, the OS fetches a new TSW 
from the user's UDL. The location specified by the new TSW is 
the entry point to the appropriate trap service routine. The 
effect of this is a forced branch into a subroutine that handles 
the special conditions represented by the fault. These traps are 
more fully described in Sections 3.5.1 through 3.5.5. 


The second category consists of asynchronous’ software events, 
known as task queue service events. Unlike the specific events 
described above, software-based traps are handled by ae single 
trap service routine, referred to as the task queue service 
routine, and a data structure referred to as a task queue. 
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Task-handled traps use the data structures and procedures 
previously discussed. The task queue is added as an information 
transfer mechanism. Task queue service is fully described in 
Section 3.5.6. 


The third category of task-handled traps are user-defined traps. 
User-defined traps allow the assembly programmer to insert in the 
program coding specific SVC14 calls to a trap routine. When the 
SVC14 is encountered, the user is trapped to the SvC14 trap 
handler exactly as described in the category 1 traps. This 
mechanism is frequently used as a debugging aid for Perkin-Elmer 
debugging packages. User-defined traps are more fully described 
in Section 3.5.7. 


Section 3.6 provides examples of programming techniques and tips 
for effective use of task-handled traps in various programming 
languages. 


3.5.1 Arithmetic Fault Trap 


An arithmetic fault trap can result from any one of the events 
listed in Table 3-4. 


TABLE 3-4 ARITHMETIC FAULT TRAP-CAUSING EVENTS 
(REASON CODE IN UDL 83('53')) 


re eee ee ee mere cme ee ee wm me ee me ee mer em ee ems me me ee ee es ee ee ee ee ee ee ee ee ee 


| | REASON | 
| Fixed point zero divide X'OO' | 
| Fixed point quotient overflow | xX'Ol' | 
! Floating point zero divide | X'02' | 
| Floating point exponent underflow ! X'03' | 
Floating point exponent overflow ! x'0O4' 


When an arithmetic fault occurs with the TSW.AFM bit set in the 
TSW, the current TSW is stored in the UDL.ARFO field, and the new 
TSW in the UDL.ARFN field is loaded and becomes the current TSW. 
The reason code is stored in the UDL.ARFF field. The LOC of the 
new TSW contains the address of the arithmetic fault trap service 
routine. The action taken when an arithmetic fault trap occurs 
depends on the options specified by Link and the traps enabled in 
both the TSW and PSW. 
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3.5.2 Data Format/Alignment Faults 


A data format or alignment fault trap results when one of the 
events listed in Table 3-5 occurs. 


TABLE 3-5 DATA FORMAT /ALIGNMENT FAULT 
TRAP-CAUSING EVENTS (REASON 
CODE IN UDL 81('51')) 


ae meen ee ee mS SE ne em came GE GS NE eT ne Ge ey ee wees es SS ee ey ee ES ee ee ee ee ee 


| REASON | 
fee teens =e teil 
| Reserved 1 x*00" | 
| Reserved | X'Ol1' | 
| Invalid sign digit, packed data | Xx'O2' | 
! Invalid data digit, packed data | X'03' | 
| Reserved | x'o4! | 
! Reserved | X'OS' | 
| Fullword alignment fault | X'O6' | 
! Halfword alignment fault ! X'07' 


comet ee ee ee ee meee cme ee ee ee eee ee ee eee wee ree ee ee re ee ee ee re ee ee re ee we ee ee 


When a data format or alignment fault trap occurs with the 
TSW.DFFM bit set, the current TSW is-_ stored in the UDL.DFFO 
field; the NTSW in the UDL.DFFN field is loaded and becomes the 
current TSW; the address of the location in memory referenced by 
the faulting instruction is stored in the UDL.DFFX field; and the 
reason code is’ stored in the UDL.DFFR field. The new TSW LOC 
contains the address of the data format or alignment fault trap 
service routine. This trap service routine exits by issuing an 
LTSW macro or SVC9 call to load the TSW stored in the UDL.DFFO 
field as the current TSW. 
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3.5.3 Power Restoration 


A power restoration trap occurs after power is restored following 
a power failure and the TSW.PWRM bit in the TSW is set. The 
current TSW is stored in the UDL.PWRO field, and the new TSW in 
the UDL.PWRN field is loaded and becomes the current TSW. The 
LOC of the new TSW snouid contain the address of the power 
restoration trap service routine. This trap service routine 
exits by issuing an LTSW macro or SVC9 call to load the TSW 
stored in the UDL.PWRO field as the current TSW. 


3.5.4 [Illegal Instruction Faults 


An illegal instruction trap occurs after a user task (u-task) 
executes an illegal instruction with the TSW.IITM bit set. The 
current TSW is stored in the UDL.IITO field, and the new TSW in 
the UDL.IITN field is loaded and becomes the current TSW. The 
new TSW LOC should contain the address of the illegal instruction 
trap service routine. This trap service routine exits by issuing 
an LTSW macro call to load the TSW stored in the UDL.IITO field 
as the current TSW. 


3.5.5 Memory Access Faults 


A memory access fault trap occurs when one of the events’ listed 
in Table 3-6 occurs. 
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TABLE 3-6 MEMORY ACCESS FAULT TRAP-CAUSING EVENTS 


» 
tf 
Oo 
z 
Q 
Oo 
Oo 
| 
N 


te] 
J 
a 
| 
Ww 
NS) 
Nh 
O 
: 


nae eet IOs oT VES ete a ALP Pe RD el PE EE ae EO RN eet) ee ee ee ' 
| SVC address error X'OO' N/A ! 
! Execute protect violation | X'Ol1' ! X'OL' | 
| Write/interrupt protect violation | X'O2' | X'O02' | 
| Read protect violation | N/A | x'Q3° | 
| Access level fault ! N/A | x'o4' ! 
| Segment limit fault | xX'10' | x'QS' | 
| Nonpresent segment fault | N/A | X'0O6! | 
| Shared segment table (SST) size exceeded | N/A | X'O7' | 
! Private segment table (PST) size exceeded ! xX'O08' "X08 ° 


When a memory access fault occurs with the TSW.MAFM bit set, the 
current TSW is stored in the UDL.MAFO field; the new TSW in the 
UDL.MAFN field is loaded and becomes the current TSW; and the 
faulting instruction address is stored in the UDL.MAFR field. 
The new TSW LOC should contain the address of the memory access 
fault trap service routine. This trap service routine exits by 
issuing an LTSW macro or SVC9 call to load the TSW stored in the 
UDL.MAFO field as the current TSW. 


3.5.6 Task Queue Trap-Causing Events and Task Queue Service 


A task queue is in the form of a standard Perkin-Elmer’ circular 
list, as shown in Figure 3-4. 
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5617 


0 15 16 31 


NUMBER OF SLOTS NUMBER OF SLOTS USED 


CURRENT TOP 


NEXT BOTTOM 


SLOT n 


Figure 3-4 Perkin-Elmer Standard Circular List 


The first four halfwords of the circular list make up the list 
header that contains the list parameters. Immediately following 
the header is the list itself. The first fullword in the list is 
designated slot 0. The remaining slots are numbered sequentially 
from 1 up to a maximum of X'FFFE'. Hence, a task queue can 
contain a maximum of 65,535 fullword. slots. For further 
information on list processing, refer to the Instruction Set 
Reference Manual for any Perkin-Elmer 32-bit processor. 


When a software fault trap occurs, entries are added to the 
bottom of the list. The user-supplied task queue service routine 
should always remove entries from the top of the queue. 


Except for the subtask change event and the APU signaling the 
CPU, all items added to the task queue, by OS/32, are four bytes 
long and have the following format. 


suete mow) eres women pms ems eee SR OS en me meen eee ee fore ee SE a re ee ee es RD Se ce my wey ee 


! Reason } 
' code H Parameter 


we wee ees seme mee geen me ee ee es es Se ee es me ee EY Se Oey See eee ere SE GE ore ee eee em te wee ree 


Bits 0 7 8 31 


Figure 3-5 Fullword Task Queue Entry 
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Reason codes and parameter information can be found in Table 3-7. 
Table 3-7 lists the fullword entries added to the list by the 
task queue trap-causing events. 


TABLE 3-7 TASK 


i 
4 
4 


QUEUE TRAP-CAUSING EVENTS 


OG ere re em ne cee mee ee mee ce ee mee oe cee me me me en ee Re ce me em me ee ee me ee cm ee me ce SY ee ne Se mY che nm mee wn ee Nene mam we ly ce ee me ks Mae mer em ly Meee eS ee 
a 


TASK 


mr ce ce ee ee eee es in es ee ee ee re ee ee ee ee ee ee ee ee ee ee i ee 


Ne AEE IE Oe, 


EVENT 


(SVC6) ! 


QUEUE FULLWORD ENTRY 
CONTENTS OF 
3-BYTE PARAMETER 


Associated with trap- 
generating device 


Specified by the task that 
issued the SVC6 


ee ee ee mare ee cee ne me ee cee emer cree cen me mn me ms es ee me ee mee oe ee ee ek eee cee ee ee eee ee wee ee ee ee ese ee ee es es ee ee 


A(send data message 
buffer ) 


es cae amare mes ets ns me a ek me ee cee ee meee ee er mmm ese es ee re ee ee ee cn ee ee ee ee ee ee eee ee eee me ee ee 


APU number, status, and 
error code (see Figure 
3-7) 


et me tere me ee cee cs ee ee sme mee es ee ces ee ae ce ee ee ee ee ee ee ee ee ce ome ee ee es ee ee es ee ee ee ree ee ee ee eee ee ee ee et ee 


(SVC6) 


ee ee ee ao ee re ee eet oe ee ee re eer ee oe oes oe 


Load proceed completion } 
(SVC6) 


ae ee me en me ee es ee ee ee ee our sete: es me ee oe ee eee ee ee ee ee ee ce ee ee ee ee ee eee ere ee es cee me wee en ee oe 


ee mee erm mm ee cert ee mm cmt meee me eee me reece neem cere ee cee mee ee eee ee ee cme ee ee cee ee mee ee ee ee me ee er cree ee ee ee eee ee ee ee omen ne ee eee ee ee re ee eee 


(SVC6) ! 


Timer completion 
(SVC2, 23) 
' 
| 


Time interval specified by 
the SVC2 code 23 param- 
eter block 


He ee nem ee ee ne nS ee ee er re rm mn GS ee er ie ee me OD ee a Oe OT Oe Ee GR mn ee ee Oe Swe eS ee ee ee ee oe 


ee Se ne eT ES MN HO AY LN AD GED ENS ON SI OD SE END RN US NY SOS SOUR TD RS SEE SE SS GD SUEY ED GU ERS ees UL a RE ER OE DS A EE ENE SD mS ery ee eee Sem ee es om tee 


econ cas ay ny ee my ty ks tn me nem NY an SE ne ao em ey ees em ee em ees en Se DS ee ee ee et me le Me OE SU OE WE TY RE OR EE EE SEE GE Ree me ce es ee ni ye 


SVCl buffer transfer | 
Seid aniagstces H 


re tet ee tne ms: Sn ta a em ee, Ye ee ee ee mes me ee ee ee cee eee me me ee ee ee ee ee ee ee ee 


A(UDR list) 
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TABLE 3--7 TASK QUEUE TRAP-CAUSING EVENTS (Continued) 


em me me me mee cee mre ees ee res mmr mm mre ree Sem rms me cet tree iy ee ee aes rere mee me cme ee me ne mee ey ce me en ees ee ee ie rte ste ne ee ee ee 


i 

1 i 

| 1I-BYTE !} 

i; REASON } CONTENTS OF H 

EVENT | CODE { 3-BYTE PARAMETER H 

SoS SSS SSS SSS SVS SSS SSS SS SS SS SASS KS SSS SSS SSS SSeS SSS Ss sees es | 
ZDLC buffer output {| X'OF' | A(UDW list) H 

Gees Ys Fer “ln a ea nha ate Sen, ec “abc ah ern i a sa Se as cops esos mc "ase rae jn aan es a cs NS ppc cance iy aa a a i 
ZDLC error condition } X'10' | ACinformation block) { 

a gy mC a a ees cnt es ems pun cow le to eS i ae cen ne ao Nee cn aS aaa pa a lel a eee aml vs a Se esas oes Gece enna cee wt cen ay aden vet eae H 
ZDLC buffer error ; X'1l1it | ACUOR list) i 

ee cone Sek ene Gen Am fete GD ET fabs mes TED ume main cman GRD Ow Nem GEES GEES GODS EON We Gee OED Ginn Son cum Me MS eee GMD Sows mee) Ge Geer cow me mime cee meee ODE mn ee On Oe: Gm cee mie cents cw en eee OY OU Oe oes Oe ee me ee es | 
EMT 3270 unsolicited Po ie": 4 ~ | 

host input 

tin spi nel sm ie pit a Sa Ele i ih aise, oe iti’ Se ei Sl, soi apa ea la. oe’: ome ss GAS es li elie. Se mes sl pi dee: eee Gabe’ psn ca Sia H 
EMT 3270 unrequested » im L£9*. | = 1 

disconnect H 

(GoGo et Sa es iano * went Sui ks eich ein sa os bts “ony wes sisi enh ms ‘ics cs ea "Sin “pS “wisn “emi i+ Ss"ases ei’ oem (StS i’ a AY ein onsen “atk ea ts sachs a aig "to H 


EMT switched line i X'lA’ 
connect time-out } 


Ne ee ee ee ee 


* The letter A indicates that the 3-byte Q entry is an address. 


NOTE 


For more information on the 0OS/32 
supervisor routines that initiate task 
queue service trap-causing events, see 
the appropriate svc in the OS /32 
Supervisor Call (SVC) Reference Manual. 


Task queue entries that are added to a monitor's task queue when 
its subtask experiences a state change are shown in Figure 3-6. 
Note that a subtask state change adds three fullword entries to 
the bottom of the quéue. The first fullword consists of a 1-byte 
reason code (X'02'), a 1l-byte subtask reason code (see Table 3-8) 
and other subtask information items. The remaining fullword 
slots contain the name of the subtask. 
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5618-1 


PREVIOUS ENTRY SLOT 1 


REASON SUBTASK ADDITIONAL 


CODE REASON SUBTASK SLOT 2 
X'02’ CODE INFORMATION 
NAME OF SLOT 3 
SUBTASK SLOT 4 
SLOT 5 
BYTES 
0 1 2 3 


Figure 3-6 Circular List with Task Queue Entries 
for Subtask State Change 


TABLE 3-8 SUBTASK REASON CODES AND 
CORRESPONDING STATE CHANGES 


same me es eee ee ee ce meee ce me ee es ee ee ee ee ree se ee ee 


| SUBTASK jj; 
' REASON } 
| CODE SUBTASK STATE CHANGE 1 
|, SSS Ste SSS eee SSeS See SSS SS SS SS SS SSS See Sess Sss | 
i; X%'OO' | End of task; bytes 2 and 3 are 
H |} binary end of task codes H 
1 ‘ ' 
' | ' 
i; X'OoOl' | Paused | 
( J 5 
' ' t 
i X'O2' ; Continued H 
i) ' t 
{ | ' 
; X'O3' | Suspended 
‘ ! i 
t ( ’ 
; X'O4' | Released H 
1 1 ‘ 
t | ! 
1 X'OS' + Rolled out 
| X‘'O6! } Rolled in | 
i \ { 
| { ' 
1 X'O7' ; Started by a task other than the } 
{| monitor 
1 ' i 
1 | { 
i; xX‘'O8' | Accounting overflow (MTM or H 
1 | t 
{ | ' 


AFDCB only) 


Ne ee ee 
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In a Model 3200MPS System, a task can receive a trap in response 
to the auxiliary processing unit (APU) signals that indicate APU 
state changes or _ errors. Section 3.6.3 describes the SVC6 
CONNECT and THAW functions that associate APUs with the _ task. 
Figure 3-7 shows’ the format of the task queue entry for an APU 
signal. 


6022-1 


pect APU APU 
oe NUMBER STATUS 
CODE 


BYTE: 
0 1 2 3 


Figure 3-7 Task Queue Entry for APU Signal 


Fields: 

APU Signal Code is X'OS5°. 

APU Number is a l-byte field specifying a decimal 
number (1 through 9) indicating the 
number of the APU from which the signal 
was received. 

APU Status Code is a 1-byte field whose contents 
correspond to the response byte of the 
SvC13 APU hardware status field. 

APU Error Code is a 1-byte field whose contents 


correspond to the error byte of the SVC13 
APU hardware status field. An X'80‘' code 
indicates that no errors exist. 


NOTE 


For information concerning the 
SVvC13 APU hardware status 


field, consult the 0S/32 
Supervisor Call (SVC) Reference 
Manual. 
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An APU signal entry can be made to the task queue in order to: 


e Indicate that the APU is entering the queue wait state. For 
example, the APU is waiting for the CPU to place a TCB on the 
empty APU queue; no errors exist. In this instance, the APU 
status code is set to X'Cl1l' and the APU error code is set to 
X'80'. 


@ Indicate that the APU has returned a TCB to the APU queue; no 
errors exist. In this instance, the APU status code is set to 
X¥'C2' and the APU error code is set to X'80'. 


e Indicate that the APU has placed a TCB on the CPU receive 
queue; no errors exist. In this instance, the APU status code 
is set to X'43' and the error code is set to X'80'. 


@e Indicate that the APU has detected an error in system data 
structures at an arbitrary moment. In this instance, the APU 
status code is set to X‘'C4' and the error code indicates’ the 
particular APU error condition. 


e Indicate that the APU has detected an error in system data 
structures during the queue wait state. In this instance, the 
APU status code is set to X'45' and the error code indicates 
the particular APU error condition. 


@ Indicate that the APU has detected an error in system data 
structures during the queue lock state. In this instance, the 
APU status code is set to X'46' and the error code indicates 
tha particular APU error condition. 


3.5.7 User-Defined Trap-Causing Events 


The OS/32 supervisor routine called by SsSvCc14 allows the 
programmer to define trap-causing events for a task. SVC14 
suspends task execution, saves the current state of the task, and 
transfers execution to the SVC14 task trap-handling routine. 


One argument can be specified when SVC14 is called. This 
argument can point to a memory location that contains a reason 
code for the user-defined trap-causing events. See the 08/32 
Supervisor Call (SVC) Reference Manual for more information on 
using SVC14. 


3.6 WRITING TASKS THAT HANDLE TASK TRAPS 
A task cannot handle a trap until it has a TSW with the 


appropriate trap bits enabled in the TCB and a TSW with the 
address of the trap-handling routine in the UDL. 
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The OS/32 system structure macro library, SYSSTRUC.MLB, provides 
macro instructions that automatically set up a UDL or TSW within 
a task's address space. The $UDL instruction defines the  UDL 
structure; the $§TSW instruction defines a TSW structure. To 
prepare a task to handle ae trap, simply execute these 
instructions and set the appropriate fields or bit masks for the 
trap that the task is to handle. 


For example, suppose a program is to output its own message and 
pause each time it attempts to execute an illegal instruction. 
First, place the address of the task trap routine in the illegal 
instruction new TSW field (UDL.IITN) as follows: 


7 


Example: 

MLIBS 8 FETCHES SYSSTRUC.MLB 
NLSTM SUPPRESSES MACRO LISTING 
$UDL MACRO TO DEFINE UDL STRUC 
ABS 0 

MYUDL DS UDL, 

MYUDLE EQU * 
ORG §MYUDL+UDL.IITN SET LOC TO FIELD 
Dc 0 DISABLES TASK TRAPS FOR NTSW 
Dc A( TRAP) PLACES ADDRESS OF TRAP ROUTINE IN NTSW 
ORG MYUDLE SET LOC TO END OF UDL 


Next, build a TSW with the TSW.IITM bit mask set. 


Example: 
NLSTM SUPPRESSES MACRO LISTING 
$TSW MACRO TO EXPAND TSW EQUATES 
NTSW Dc TSW.IITM SETS ILLEGAL INSTRUC TRAP BIT 
Dc 9) SETS LOC AT INSTRUC FOLLOWING SVC9 


After initiation is completed , the task will execute the "TRAP" 
label and will then issue an SVC9 to load this TSW into the TCB 
as follows: 


TRAP SVC 2,MSG 
svc 2,PAUSE 
svc 9,NTSW 


Table 3-9 summarizes the UDL fields and TSW bit masks’ that 
pertain to each type of task trap. 
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TABLE 3-9 SUMMARY OF TASK STRUCTURES USED FOR HANDLING 
TRAPS (Continued) 


NN Oe em mE SEE IES Me wr cee Boe ee Ee mS SO Mire MEE (ee Mee Bete mele ee mee cme Em Oe mee aimee ee ent te ee en me ene ie ee ee ie ere: ee noes eee ee ee 


UDL | TASK | 

| TRAP-CAUSING EVENT  ; FIELDS {| QUEUE {| TSW BIT MASK 
| == Sete ete SSS Eee Sa ef VCecs SSS MB STS See cE aS ETT est =z 
i Send Data*** i UDL.TSKO ;{ Yes TSW.TSKM 

|} (SVC6) } UDL.TSKN | TSW.SDM 

i} UDL.TSKQ | 

| UDL.SDQ 

{ ce see cae ee me eae fos San tue noe ee Me ae eee eee fe oe omen mm ae ame : cee te ae ees eee eee ee ee ae H mae ee H ee ae eee aes ee ee ee ee cae ee eee ee 
| Send Message*** | UDL.TSKO | Yes TSW. TSKM 

| (SVC6) | UDL.TSKN | TSW. PMM 

{| UDL.TSKQ | 

{| UDL.MSGR } 

aaa cantina emcee aaa aia apres aaa onesies Sree gases 
i Send Queue | UDL.TSKO | Yes TSW. TSKM 

i Parameter } UDI..TSKN | TSW.TCM 

| (SVC6) | UDL.TSKQ | 

| ee ee rae re ae ee ee ee ee a en H ne sare eee sae ae ers cre ee ee ee ete Fes a ee a ea a ata 
H Subtask State i; UDL.TSKO {| Yes TSW.TSKM 

| Change } UDL.TSKN | TSW .SUQM 

i (SVC6) } UDL.TSKQ | 

i ee ae ee ee ee | ee ee ee { ee ' a ee ee ce a ee 
{ SVC14 } UDL.S140 {| No TSW.S14M 

} UDL.S14N_ | 

} UDL.SV14 | 

H me ee ee ee ee ee ee ee i we ee ‘ eee ee } a ee ee eee 
i Timer Termination i UDL.TSKO | Yes TSW .TSKM 

| (SVC2 code 23) | UDL.TSKN | TSM .TMCM 

|} UDL.TSKQ | 

a ae da alia ca pe nae ren Feats aaa eccee erie erea iy aes 
TEap Wait ; | No TSM.WIM 

* Available on Perkin-Elmer Series 3200 


processors only. 


wx Task must be lLinked-edited with NAFPAUSE task 
option enabled. 


xxx Task must also include a message buffer to receive 
the message. See the OS/32 Supervisor Call (SVC) 
Reference Manual. 


x**x*x Available with the Model 3200MPS System only. 


NOTE 
A task can be suspended until a 


trap-causing event occurs by setting the 
TSW.WIM bit in the TSW. 
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3.6.1 Handling Task Queue Traps 


In addition to the UDL and TSW, a program that handles task queue 
traps must have a task queue. The DLIST instruction can be used 
to build a circular list for the task queue as follows: 


QUEUE DLIST 3 


The following example builds a UDL structure for a task that 
handles I/O proceed completion traps. Note that the address of 
the task queue is placed in the UDL.TSKQ field. 


Example: 
MLIBS 8 FETCHES SYSSTRUC .MLB 
NLSTM SUPPRESSES MACRO LISTING 
$UDL MACRO TO DEFINE UDL STRUC 
ABS 0 
MYUDL DS UDL 


MYUDLE EQU- * 
ORG MYUDL+UDL.TSKQ 


DC A( QUEUE ) INITS ADDRESS OF TASK QUEUE 

ORG MYUDL+UDL. TSKN 

DC TSW. 10M QUEUE ENTRY - I/O COMPLETION 

DC A( TRAP ) INITS ADDR OF TASK QUEUE HANDLER 


ORG MYUDLE 


The TSW for a task handling an input/output (1/0) proceed 
completion trap is initialized as follows: 


$TSW 
NTSW DC TSW. TSKM! TSW. IOM SETS TASK QUEUE & I/O PROCEED BITS 
DC 6) 


If a task queue trap is a send data trap, the task requires a 
message buffer queue to receive the message sent by the trap. 
The address of this queue is placed in the UDL.SDQ field. 


Send message traps require a message ring whose address is placed 
in the UDL.MSGR field. For more information on how to set up a 
message ring or send data buffer queue, see Chapter 6 (SVC6) in 
the OS/32 Supervisor Call (SVC) Reference Manual. 
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The following code sets up a UDL, TSW, task queue and message 
ring for a task to service a send message trap. 


Example: 
MLIBS 8 FETCHES SYSSTRUC .MLB 
NLSTM SUPPRESSES MACRO LISTING 
$UDL MACRO TO DEFINE UDL STRUC 
$TSW MACRO TO EXPAND TSW EQUATES 
ABS 0 


MYUDL DS UDL 
MYUDLE EQU . 
ORG MYUDL+UDL. TSKQ 


DC A (QUEUE) STORES TASK QUEUE ADDR 

ORG MYUDL+UDL .MSGR 

DC A(MESS1) STORES MESSAGE RING ADDR 

ORG MYUDL+UDL.TSKN 

DC 0 

DC A( TRAP ) STORES TRAP HANDLER ADDR IN LOC 


ORG MYUDLE 
QUEUE DLIST 3 


TSW pc TSW. TSKM! TSW. PMM SETS TSK Q AND SEND MESS TRAP BITS 
DC 8) 
ALIGN 4 
MESS1 pc A(MESS2) 
DS 72 
MESS2 DC A(MESS1) 
DS 72 


3.6.2 Tips for Writing Task Trap-Handling Routines 


The task trap-handling routine should contain all the program 
code necessary to process the trap. Because no registers are 
saved as part of the TSW swap that causes a trap-handling routine 
to be initiated, the routine should save the contents of any 
registers required by the task. 


Task queue trap-handling routines should contain code that will 
remove items from the task queue. For example, suppose a send 


message trap placed the following item in slot five of the task 
queue: 


O06 A(MESS1) 
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The following example demonstrates one 


item from the task queue. 


Example: 


TRAP 


TRAPEXIT 


To resume task execution, 
old TSW in the UDL to the TCB. 
See the OS/32 Supervisor 


issued an SVC 


ie 


* 


RO, TRAPSAVE 


2,WRITE+SVC.1.SAD 
2,63(2) 
2,WRITE+SVC1.EAD 


2,0 

2,0(1) 

TRAP 

x 

RO, TRAPSAVE 
9,UDL.TSKO 


Manual for more information. 


3.6.3 


method of removing this 


SAVE REGS (OPTIONAL) 
TRANSFER QUEUE ITEM TO RL 
QUEUE EMPTY 


VERIFY REASON CODE 


SHIFT Rl ONE BYTE TO. RIGHT 
(Rl)+12 IS MESS START ADR 
STORE ADR IN SVCl PARBLK 
(R2)+63 IS MESS END ADR 
STORE ADR IN SVCl PARBLK 


RESET BUFFER FALL BIT IN 
MESSAGE BUFFER 
SEE IF ANY MORE ON QUEUE 


RESTORE REGS (OPTIONAL) 
LOAD OLD TSW 


a trap-handling routine must return the 
In the above example, the routine 


Call (SVC) Reference 


Handling Traps From Trap-Generating Devices 


OS/32 provides intertask control services that allow a task to 


receive 


Connect 


Thaw 


Sint 


Freeze 


Unconnect 


a trap 
services include: 


from an external trap-generating device. 


These 


attaches a trap-generating device to a task. 


enables 


interrupts 


from the attached 


trap-generating device. 


simulates an interrupt froma 


device. 


disables 


interrupts 


trap-generating 


from the attached 


trap-generating device. 


detaches a trap-generating device from a task. 
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These services implement the proposed standards established by 
the Instrument Society of America (ISA) for electronic devices. 


An example of a task that receives and handles traps from 
trap-generating devices is the Perkin-Elmer 8-line interrupt 
module driver. To handle a trap received from a trap-generating 
device, the task sets the TSW.TSKM and TSW.DIOM bits in the TSW. 
The task also builds a task queue to receive an entry from the 
device when an interrupt occurs. Using the OS/32 intertask 
control services and data structures for handling task queue 
traps, the user can write a task that handles traps from external 
devices. 


The OS/32 intertask control services can also be used to attach 
an APU to a task and enable interrupts from the APU each time it 
sends a signal to the CPU in a Model 3200MPS System. To handle 
a trap generated by an APU signal, the task must have the 
TSW.APTM and TSW.TSKM bits set in the TSW. The task must also 
build a task queue to receive the interrupt information items 
from the APU. See Figure 3-4. 


See the 0S/32 Supervisor Call (SVC) Reference Manual for more 
information on the intertask control services provided by OS/32. 


3.6.4 Sample Task Trap-Handling Program 


The following assembly program (called the directed task) 
establishes an environment for handling task queue entry traps on 
the reception of a message from another task (called the calling 
task), and then places itself in a trap wait state. After the 
send message trap occurs, task execution branches to the task 
queue trap-handling routine that removes the queue entry = and 
stores the beginning and ending address of the message in an SVCL 
parameter block. The routine then outputs the message sent from 
the calling task. See the OS/32 Supervisor Call (SVC) Reference 
Manual for more information on SVC1. 


48-039 FOO RO2 3-33 


Example: 


1 PROG DIRECTED TASK WITH TRAP HANDLER 
2 MLIBS 8 FETCH SYSSTRUC.MLB 
3 NLSTM 
4 FREZE 
5 $UDL DEFINE UDL STRUC 
6 $TSW DEFINE TSW STRUC 
7 ABS 0 
8 MYUDL DS UDL RESERVE STORAGE FOR UDL 
9 MYUDLE EQU- * 
10 ORG MYUDLtUDL.TSKQ INITIALIZE UDL FIELDS 
11 pc A(QUEUE ) DEFINE TASK QUEUE LOC 
12 ORG §MYUDL+UDL.MSGR 
13 pc A(MESS1) DEFINE MESSAGE RING LOC 
14 ORG MYUDL+UDL.TSKN 
15 pc TSW. PMM 
16 Dc A(QTRAP) DEFINE NEW TSW FOR TASK TRAP HANDLER 
17 ORG MYUDLE 
18 IMPUR 
19 QUEUE DLIST 3 
20 * ENABLE TRAP WAIT,TASK Q TRAPS,MESS Q 
21 TSW Dc TSW.WIM! TSW. TSKM! TSW. PMM 
22 Dc 0 RESUME AFTER SVC9 
23 ALIGN 4 
24 MESS1 Dc A(MESS2) RESERVE STORAGE FOR MESSAGE RING 
25 DS 72 
26 MESS2 pc A(MESS1) 
27 DS 72 
28 $SVCl 
29 ALIGN 4 
30 WRITE DS SvCcl. SVCl PARAMETER BLOCK 
31 ENDBLK EQU- * 
32 ORG WRITE+SVC1.FUN 
33 DB SVL.WRITISVL.WAIT 1/0 WRITE AND WAIT FUNC 
34 DB 2 LOGICAL UNIT 2 
35 ORG  ENDBLK 
36 START EQU * 
37 svc 9,TSW ENABLE Q ENTRIES, TRAP WAIT,ENTER TRAP WAIT 
38 svc 3,0 END TASK 
39 QTRAP EQU) * 
40 RTL  1,QUEUE REMOVE QUEUE ENTRY TO RL 
41 RLL 1,8 ROTATE REASON CODE TO LOW BYTE 
42 LBR 2,1 MOVE REASON CODE TO R2 
43 CLI 2,6 IS IT A MESSAGE (RC=6) 
44 BNE ERROR NO, ABORT ON ERROR 
45 SRL 1,8 SHIFT A(MESS) BACK IN Rl 
46 LA 2,12(1) R2 = A(MESSAGE START) 
47 ST 2,WRITE+SVC1.SAD PUT ADR IN SVCl PARBLK 
48 LA 2,63(2) R2 = A(MESSAGE END) 
49 ST 2,WRITE+SVC1.EAD PUT ADR IN SVCl PARBLK 
50 svc 1,WRITE ISSUE WRITE 
51 LIS 2,0 BIT OFFSET = 0 
52 RBT 2,0(1) RELEASE MESSAGE BUFFER 
53 RBT 2,UDL.TSKO RESET TRAP WAIT IN OLD TSW 
54 svc 9,UDL.TSKO LOAD OLD TSW 
55 ERROR svc 3,4 ABORT: RETURN CODE = 4 
56 END START SPECIFY PROGRAM START ADDRESS 
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3.6.5 Using the 0S/32 System Macro Library to Handle Traps 


The OS/32 system macro library provides macro definitions for 
setting up the data structures necessary to handle task traps. 
Another macro, LTSW, performs a TSW load. The following program 
performs the same functions as_ the sample program given in 
Section 3.6.4. Notice, however, the lines of code that have been 
replaced with one-line macros. 


Example: 
LINES REPLACED BY MACROS 
MLIBS 10 
NLSTM 
QUEUE DLIST 3 
MESS 1 MSGRING 3,72 24-27 
START SETUDL TSKQ=QUEUE ,MSGR=MESS1,TSKN=(0O, TRAP) 5-17 
LTSW WT, TSKE, TMQ 21-22,37 
EOT RC=0 38 
TRAP ~ EQU * 
RTL 1,QUEUE 
RLL 1,8 
LBR 2,1 
CLI 2,6 
BNE ERROR 
SRL 1,8 
WRITE LU=2,ADDR=12(1),RECL=64 28-35,50 
LIS 2,0 
RBT 2,0(1) 
LTSW PCB=UDL.TSKO 54 
ERROR svc 3,4 
END START 


See the 0S/32 System Macro Library Reference Manual for details 
on how to use the OS/32 macro instructions for writing 
trap-handling programs. 


3.6.6 Writing FORTRAN Trap-Handling Programs 


The Perkin-Elmer FORTRAN VII Run-time Library (RTL) provides 
subroutines that allow the FORTRAN programmer to write programs 
that handle task traps. Subroutine INIT initializes the task's 
TSW, UDL, task queue and message ring. Subroutine ENABLE sets 
the appropriate TSW trap bit and stores the address of the task 
trap-handling routine in the UDL. 
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Example: 


C THIS PROGRAM SERVICES DEVICE INTERRUPTS. 
Cc 


EXTERNAL NAME 


CALL INIT 


e 


CALL ENABLE (1,NAME) 


o 


END 


C THE FOLLOWING SUBROUTINE 
C HANDLES THE TASK TRAP 
Cc 

SUBROUTINE NAME (...) 


RETURN 
END 


See the FORTRAN VII User Guide for more information on writing 
FORTRAN programs that handle task traps. 


3.6.7 Writing Pascal Trap-Handling Programs 


Writing a Pascal program that enables and handles task traps is 
very difficult, but it can be done by using a combination of 
Pascal features and OS/32 Common Assembly Language (CAL) 
routines. 


The SMPLSVCS.PAS file supplied with the Perkin-Elmer Pascal 
compiler provides constants and types’ for handling SVCs ina 
Pascal program. The following code represents a sample Pascal 
program for enabling memory access faults. 
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Example: 


PROGRAM SAMPLE; 


CONST MAFN = 35; 
TSW_ MEMF_EN = #04000000; 


TYPE UDL_INDEX = 0..63; 
VAR NEWTSW, HADDR: INTEGER; 


PROCEDURE TOUDL (I: ULD_INDEX; 

VAL: UNIV INTEGER); EXTERN; 
PROCEDURE GETHADDR (VAR HADDR: INTEGER); EXTERN; 
PROCEDURE SETTSW (NEWTSW: INTEGER); EXTERN; 
PROCEDURE SVC2PAUS; EXTERN; 


BEGIN 
GETHADDR (HADDR) ; 
TOUDL (MAFN,HADDR) ; 
NEWTSW := TSW_MEMF_EN; 
SETTSW (NEWTSW) ; 
SVC2PAUS ; 

END. 


GETHADDR PROG GET ADDRESS OF HANDLER 
, ENTRY GETHADDR 
EXTRN MEMAFH 


STACK STRUC STRUC OF ACTIVATION REC ON STACK 
OLDLB DSF 1 OLD LOCAL BASE (R2) 
RETAD DSF 1 RETURN ADDRESS 
SLINK DSF 1 STATIC LINK 
ENDS 
GETHADDR EQU- * 
ST 15,RETAD(2) SAVE RETURN ADR ON STACK 
LA 8 ,MEMAFH MOVE ADR OF HANDLER 
ST 8,0(3) TO ARGUMENT (R3 = A(HADDR)) 
L 15,RETAD(2) RESTORE RETURN ADDRESS 
L 2,OLDLB (2) RELOAD LOCAL BASE (RELEASE STACK) 
BR 15 RETURN 
END 
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SETTSW PROG SET UP NEW TSW IN’ TCB 
ENTRY SETTSW 
STACK STRUC 


OLDLB DSF 1 

RE'TAD DSF 1 

SLINK DSF L 

SVC9OBLK DSF 2 
ENDS 

SETTSW EQU * 
ST 15,RETAD(2) SAVE RETURN ADDRESS 
ST 3,SVC9IBLK (2) STORE NEW TSW ON STACK 
LIS RO,O 
st RO ,SVC9OBLK+4(2) ZERO LOC OF NEW TSW 
SVC 9,SVC9IBLK (2) LOAD NEW TSW 
L 15,RETAD(2) RESTORE RETURN ADDRESS 
L 2,OLDLB (2) RELEASE STACK 
BR 15 RETURN 
END 

MODULE MEMAF H 

BEGIN 

END 

The above example enables and handles memory access faults. The 


user-written SETTSW procedure issues an SVC9 to replace the 
Link-initialized TSW in the TCB with a TSW enabled for memory 
access) faults. The user-written procedure GETHADDR sets the 
variable HADDR to the address of the task trap-handling routine 
(MEMAFH). The procedure TOUDL places the address of this routine 
into UDL.MAFN. TOUDL is included in the SMPLSVCS.PAS file. 


Except for arithmetic fault handlers, all trap-handling programs 
require a similar user-—wr itten procedure to enable the 
appropriate trap bit. SMPLSVCS.PAS provides information about a 
procedure that automatically enables the arithmetic fault trap 
bit in the TCB. 


If the trap-handling routines are written in Pascal, the Pascal 
register set must be set up or. preserved. Entry into the 
trap-handling routine would then usually be through a CAL routine 
that establishes the register set. A separate stack/heap area 
may need to be set up in such a CAL routine. 


For more information on traps and interfaces between Pascal and 
CAL routines, see the Perkin-Elmer Pascal User Guide, Language 
Reference and Run-Time Support Reference Manuals. 


W 
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CHAPTER 4 
OS/32 DISK FILE MANAGEMENT SERVICES 


4.1 INTRODUCTION TO THE OS/32 FILE MANAGER 


Application programs read and write data through the peripheral 
devices connected to the computer. In addition to such 
input/output (1/0) operations as logging messages on the system 
console or reading data from a multi-terminal monitor (MTM) 
terminal, a task should be able to store any amount of data _ for 
future use. All tasks within a system should be able to store, 
move, and update all information required by the user's 
application. 


The OS/32 file manager stores and retrieves information for a 
task on secondary storage devices (disks, magnetic tapes, floppy 


disks, etc.). The file manager partitions this storage into 
smaller areas, called files, that can be used by tasks for data 
and program storage. In addition, the file manager provides 


tasks with the following support services for management of files 
on disk: 


Allocate initializes a file by allocating space on 
disk. 

Delete removes a file from disk. 

Rename changes the name of a file. 

Open assigns a file to a task. 

Close releases a file (cancels an existing 


assignment) when a task has completed its use 
of the file. 


Fetch examines the attributes of a file. 
Attributes 
Checkpoint ensures that all data in an output buffer is 


written to disk. 


This chapter describes the OS/32 structures that are used by the 
file manager to provide these services. 
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4.2 SYSTEM RESOURCE MANAGEMENT 


The file manager controls two types of system resources for a 
task: files and the devices that store and retrieve files. 


A file is a named collection of data records on a_ secondary 
storage device. Secondary storage devices supported by the file 
manager include fixed-hnead disks, moving-head disks, and floppy 
disks. Fixed-head disk drives have smaller average access times 
than moving-head disks, while moving-head disks typically have 
larger storage capacities. 


Devices are read from or written to like ordinary disk files; 
l.e., a task performs a data transfer to a device in the same 
manner it would perform a data transfer to a file on disk. 
However, when a task performs an 1/0 operation to a device (such 
as a printer, data communications device, magnetic tape, etc.), 
data must be transferred via an appropriate protocol determined 
by the device driver. Device drivers are system software modules 
that make the device look like an ordinary disk file to the file 
manager. These drivers are included in the O0S/32 I/O subsystem. 


Every file and device on a Perkin-Elmer system is referenced by 
a file descriptor (fd). The fd is used by the file manager to 
find and access a device or file as required by the task. 


Format: 


voln: actno 
\{ | [filename] [-ext] ) | | 
dev: file class 


Parameters: 


voln: is a l- to 4-character alphanumeric string 
specifying the name of the disk volume on 
which the file specified by filename resides. 
The first character must be alphabetic, the 
remaining alphanumeric. If this parameter is 
omitted, the default is the system volume in 
an OS/32 real-time environment or a default 
volume specified by the user in an MIM 
environment. 


dev: is a l- to 4-character alphanumeric string 
specifying the name of a device (e.g., CON:, 
PR:, NULL:, or MAGI:). The first character 
must be alphabetic, the remaining 
alphanumeric. 
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filename is a l- to 8-character alphanumeric’ string 
specifying the name of a disk file. The first 
character must be alphabetic, the remaining 


alphanumeric. If a filename is specified when 
a device name is referenced, the filename is 
ignored. 

-ext is a l- to 3-character alphanumeric string 


specifying the extension to a filename. 


actno is a decimal number ranging from 0 to 65,535, 
specifying the account number associated with 
the file. Account numbers 1 through 65,535 
(excluding 255) are used by MTM for terminal 
users. Account number 255 is reserved for the 
MTM system administrator. Account number O is 
for system files and is the default for all 
operator commands. Under MIM, only privileged 
users may specify an account number rather 
than a file class. 


file class is a l-character alphabetic string specifying 
the file class. The file classes are: 


e P for a private file 
e G for a group file 


e S for a system file 


If the file class is omitted, the default is 
P for files generated in an MTM environment 
and S for files generated in an 0S/32 
real-time environment. 


4.3 FILE ORGANIZATION 


A data record is a list of information elements that are accessed 
together. Before the file manager can store a record on a disk, 
the disk must be initialized by the 0OS/32 disk initializer 
program. See the OS/32 Fastchek Reference Manual for more 
information. Figure 4-1 shows the surface of a formatted disk. 
Note that the surface of the disk is divided into tracks. A 
track is the area covered by a stationary read/write head with 
one revolution of the disk. The amount of information that can 
be stored ona track is a function of the recording density and 
size of the track. 
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DIRECTION OF ROTATION 


TRACKS 


SECTOR 
NUMBER 


SECTOR 


Figure 4-1 Formatted Disk Surface 


When a aqaisk is initialized, the tracks are divided into sectors. 
The disk surface shown in Figure 4-1 is divided into eight 


sectors. Each sector of each track holds 256 bytes of data, the 
smallest addressable storage area on disk. 


The file manager uses two methods for organizing data records 
into files on formatted disks: 


e linked-list indexed organization, and 


@® contiguous organization. 
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4.3.1 Linked-List Indexed Organization 


When the file manager creates a file using the linked-list 
indexed organization method, it sets aside two types of storage 
areas or blocks on disk: data blocks and index blocks. These 
areas are shown in Figure 4-2. The data block is a group of one 
or more contiguous sectors that are used to store the data 
records. The index block is a group of contiguous sectors that 
store pointers to the individual data blocks. Note that index 
block 1 in Figure 4-2 points to the first sector of index block 
2. Because each index block points to its successor, the file is 
said to contain a linked-list indexed organization. One index 
block for each indexed file assigned to a task remains in dynamic 
system space as long as the file is assigned to the task. The 
unused index blocks remain on disk. For buffered indexed files, 
space for two data blocks is reserved in dynamic system space as 
long as the file remains assigned. 


pean INDEX BLOCK 1 INDEX BLOCK 2 
0(0)4 j 0(0)4 


INDEX 
BLOCK 
eo 4 ee 
| 4 
a 
SECTOR SECTOR SECTOR SECTOR 
#1 . #2 #3 #4 
| DATA 
BLOCK 
AREA 


SECTOR | SECTOR SECTOR | SECTOR 
#5 #6 #7 #8 


Figure 4-2 Linked-List Indexed File Organization 
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4.3.2 Contiguous Organization 


A contiguously organized disk file consists of a sequence of data 
blocks stored on tracks with consecutive addresses. Each block 
of data is one sector (256 bytes) in length. Contiguous files 
can be accessed randomly (by sector) or sequentially. When 
accessed sequentially, the contiguous file appears to have a 
magnetic tape-like organization; i.e., to the task the file 
resembles a magnetic tape with 256-byte blocks. For example, the 
task can write a filemark (X'1313') to the first two bytes of a 
sector in a contiguous disk file. Using the filemark as a record 
delimiter, the task can space forward or backward to the filemark 
as it would to a filemark on magnetic tape. 


4.4 DISK ORGANIZATION 


Disk packs organized under OS/32 contain two distinct categories 
of information: 


e Control information 


e User-defined data 


Control information includes the volume descriptor, bit map, file 
directory and pack administration file, which perform the 
following functions: 


e The volume descriptor is a data structure used by the file 
manager to identify the disk volume and to point to structures 
that contain the file and disk space information. 


e The bit map, also called a sector allocation map, is used to 
indicate which sectors are in use on a disk. Also, in the 
case of defective sectors, the bit map indicates which sectors 
are unusable. 


e The file directory is a file used by the file manager to keep 
track of all files on the disk. This file is organized as a 
linked-list, where each entry of the list identifies and 
describes a file on the disk. 


@e The pack administration file contains a list of defective 


sectors and a record of the administrative history of the disk 
pack. 


User-defined data includes all the contiguous’) and indexed 
application files. 
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The Mirror Disk facility maintains two identical copies of the 
user-defined files on separate disk packs. These files are 
physically synchronized by keeping them identical bit for bit and 
sector for sector. The control information is also mirrored in 
normal write and read operations in the mirrored environment. 
This control information is important in establishing whether two 
Gisks are compatible for mirroring. 


4.5 SUPPORTED DISK FILE TYPES 


How a file is organized determines the size of its data records. 
Contiguous files have a fixed record length and file length. 
Indexed organization supports fixed record lengths but the file 
is extendable. Files can extend the length of the disk volume. 
OS/32 does not support multi-volume files. 


To meet the requirements of applications running in a_ real-time 
environment, the 0OS/32 file manager supports five different types 
of disk files. These file types offer the user a flexible range 
of record lengths, file lengths and access methods. The file 
types are: 


@ Contiguous 

e Indexed 

e Nonbuffered indexed 

e Extendable contiguous 


@e Long record 


The following sections define these file types in terms of their 
record and file lengths. Access methods are discussed in Section 
4.7. 


4.5.1 Contiguous Files 


Contiguous files are organized sequentially on disk. When the 
file manager has allocated a contiguous file (i.e., reserved a 
user-specified number of contiguous sectors on disk), the maximum 
length of the file is fixed. It cannot be changed during data 
transfer. Records within a contiguous file are 256 bytes (one 
sector) in length. A read or write to a contiguous file can 
transfer any amount of data (from a partial sector to the entire 
length of the file) in a single I/O operation. Nevertheless, the 
I/O operation must begin on a sector boundary. 
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Like records stored on magnetic tape, contiguous file records are 
stored on consecutive adjacent sectors. In addition, a filemark 
can be written to the first two bytes of each record. When using 
the filemark capability, care should be taken that any data to be 
transferred to disk does not contain X'1313'. 


4.5.2 Indexed and Nonbuffered Indexed Files 


Two types of files for which the file manager uses a linked-list 
Organization are the buffered indexed and nonbuffered indexed 
files. Because these files are open-ended, the maximum length of 
either of these files is determined during data transfer. 
Maximum file length is limited only by the free space available 
on disk; however, records are restricted in size from 1 to 65,535 
bytes. In addition, because of hardware restrictions, 
nonbuffered indexed file records must be an even number of bytes 
in length. The record size is specified by the user when the 
file is allocated. Records are stored in data blocks consisting 
of one or more 256-byte contiguous sectors. 


The organization of records in a nonbuffered indexed file differs 
from that for indexed file records. Each record in a nonbuffered 
indexed file begins on a physical sector (256-byte) boundary, 
whether or not’ the previously transferred record filled up its 
sector space. Also, nonbuffered files do not have memory 
reserved in dynamic system space for data block buffers. Indexed 
file records are transferred so no unused space remains between 
two records. There are no hardware restrictions for indexed 
files. 


Data block size describes the physical block size to be used for 
buffering and debuffering operations on indexed files or data 
communications devices. Data block size represents the block 
size in sectors of the physical data blocks containing the file. 


Index block size represents the size of index blocks in sectors. 
Index blocks are actual pointers to physical data blocks. 


4.5.3 Extendable Contiguous Files 


The third type of file that uses a linked-list organization is 
the extendable contiguous file. Like the indexed and nonbuffered 
indexed files, the maximum length of an extendable contiguous 
file can be extended by write operations. A random write to a 
record past the current end of file will cause that record to 
become the new end of file, and empty records will be created 
between the previous last record and the new last record. 
However, like contiguous files, the record length is fixed at 256 
bytes (1 sector), and any number of sectors can be transferred in 
a single I/O operation. 


4-8 48-039 FOO RO2 


4.5.4 Long Record Files 


OS/32 also supports the long record file type which is used to 
perform 1/0 operations with very large logical record lengths. 
This file type is similar to an extendable contiguous file but 
differs in that the logical record length of the long record file 
is specified by its data block size. 


For long record files the maximum size of a data block is 65,535 
(64K) sectors, which is equivalent to an absolute maximum logical 
record length of 16,776,960 (16M) bytes. With the use of a long 
record file, a maximum of 16Mb of data can be read from or 
written to memory with a single I/O command. In practice, 
however, the actual maximum logical record length for any given 
system is limited by the amount of memory available for I/O 
buffering. 


4.6 MIRROR DISK ENVIRONMENT 


The Mirror Disks facility provides a service such that in the 
event of a disk failure a system can continue normal operation 
using a duplicate copy of the failed disk. This is made possible 
by maintaining pairs of disks in physical synchronization. Disks 
are physically sychronized if the user-defined data files are 
identical bit for bit. One disk is designated as the primary 
disk and the other is designated as the secondary disk. 


The only necessary hardware to support the facility is the extra 
disks required. These must be the same size as those which are 
to be mirrored. 


During normal operation, any write to a mirrored disk will result 
in writes to both disks. This not only includes writes to the 
files themselves, but also file allocation, file renaming, etc. 
Control is returned once both writes are complete. If one disk 
fails, the system continues normal operation using the remaining 
good disk. Reads are scheduled from one disk only, the primary 
disk. In the event that an attempt to read from the primary disk 
fails, data is read from the secondary disk instead. The 
programmer interface is essentially unchanged. It is possible, 
however, to detect when a primary read has failed. This requires 
an extended option as described in the OS/32 Supervisor Call 
(SVC) Reference Manual. 


4.6.1 Disk Failure 
In the case of a failure of one of a mirrored pair of disks, the 


following occurs: 


® Repeated messages are output to the system console, at regular 
intervals, indicating the disks are no longer synchronized. 
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e The secondary disk immediately takes over if the primary disk 
failed, with no interruption to the system software using the 
disk. 


4.6.2 Normal Input/Output (1/0) Performance 


The disks of a mirrored pair should be on separate. selector 
channels (SELCHs) to ensure the efficiency of write operations to 
the mirrored disks. These disks are not required to be on 
separate SELCHs, but if they are, the performance degradation is 
likely to be minimal. 


Degradation varies according to the volume of data being written 
for mirror disks that are on the same SELCH. It is estimated 
that it takes 22% longer to write a sector and 45% longer to 
write a 16kb buffer in a mirrored environment. Read operations 
are not adversely affected. 


The Mirror Disk facility is designed to be user-transparent. 
However, extended SVCl options are available (see the OS/32 
Supervisor Call (SVC) Reference Manual for more information). 


4.7 DISK SPACE MANAGEMENT 


In servicing task file requests, the file manager must: 


@ Allocate file directory entries and index blocks. 


e Allocate a sufficient amount of disk space to contain the file 
(e.g., contiguous files). 


e Extend the space already allocated to a file (indexed, 
nonbuffered indexed, extendable contiguous or long record) by 
allocating additional index blocks and data blocks. 


@® Delete a file and return the space to the available space 
inventory. 


4.8 VOLUME DESCRIPTOR 


The file manager must keep track of all the files on a disk and 
the storage space available to the files to perform it's 
operations effectively. A special data structure, called the 
volume descriptor, is used by the file manager to identify the 
disk volume and to point to structures that contain the file and 
disk space information. 


The volume descriptor is shown in Figure 4-3. When formatting 
the disk, the Fastchek Utility initializes the volume descriptor 
in logical block address (LBA) O (sector 0, head 0, cylinder 0). 
Refer to the OS/32 Fastchek Reference Manual. 
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0(0) VOL (4) 
VOLUME NAME 


4(4) ATRB (4) 
VOLUME ATTRIBUTES 


FDP (4) 
FIRST DIRECTORY BLOCK POINTER 


12(C) OSP (4) 

POINTER TO OS IMAGE (UNUSED) 
16(10) OSS (4) 

SIZE OF OS IMAGE (UNUSED) 


20(14) MAP (4) 
POINTER TO BIT MAP 
RESERVED FOR OS/16 
SDP (4) 
SECOND DIRECTORY BLOCK POINTER 


28(1C) 


32(20) SYNC (4) 
SYNCHRONIZATION STAMP 


Figure 4-3 Volume Descriptor 


The volume descriptor is used asthe basis for establishing 
whether a pair of disks are synchronized and mirrored. The 
following fields of the volume descriptor are used: 

e Disk volume name 

@e Volume on-line bit of the attribute words 

e First directory block pointer 

@ Pointer to the bit map 

@® Synchronization stamp 

After the initial synchronization of the _ two disks, the 


synchronization stamp is the main factor used to control the 
mirror disk operation. 
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The stamp is initialized to zero whenever a disk pack is 
initialized or checked by the Fastchek Utility. A zero setting 
indicates that the Synchronization Utility (DISCSYNC) must be 
run. See the 0S/32 System Support. Utilities Reference Manual for 
information. It is important that disk packs used for mirroring 
are initialized by the Fastchek Utility. 


The synchronization stamp is only calculated and placed in the 
volume descriptor when a pair of mirrored disks are marked off 
together. The stamp is cleared again when the disks are marked 
on. In all circumstances, the synchronization stamp remains with 
a zero setting and must’ be resynchronized using the DISCSYNC 
Utility when used as a mirrored pair again. 


4.8.1 File Directories 


The file manager keeps track of all the files on the disk through 
the primary file directory. This file is organized as a_ linked 
list of one-sector directory blocks. Figure 4-4 shows one block 
of a primary directory. Note that it contains five directory 
entries and a pointer to the next primary directory block. 
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0 (0) 4 
NEXT DIRECTORY BLOCK POINTER 

4 (4) 48 
DIRECTORY ENTRY 1 

2 34 

? os DIRECTORY ENTRY 2 ste 

100 (64) 48 
DIRECTORY ENTRY 3. 

148 (94) 48 
DIRECTORY ENTRY 4 . 

196 C4 4 

ose DIRECTORY ENTRY 5 : 


256 = (100) 


Figure 4-4 Primary Directory Block 
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FNM (8) 
FILE NAME 


EXT (3) 11(8) ACT (1) 
EXTENSION ACCT NUMBER 


FLBA (4) 
FIRST LOGICAL BLOCK ADDRESS 


16(10) LLBA (4) 


LAST LOGICAL BLOCK ADDRESS 
20(14) WKEY (1) 21(15) RKEY (1) 22(16) LRCL (2) 
WRITE KEY READ KEY LOGICAL RECORD LENGTH 
24(18) DATE (4) 


DATE FILE ALLOCATED 


28(1C) LUSE (4) 


DATE FILE LAST WRITTEN 


32(20) WCNT (2) 34(22) RCNT (2) 
WRITE COUNT READ COUNT 


36(24) 37(25) aRi26 ee SHDS (1) 
Revaisures ee om Bie oeu (27) S4ARED DISK SUPPORT 
ge LOCK SI . INDEX BLOCK SIZE (BOOENSEEWERE) 


40(28) CSEC (4) 
# CURRENT SECTOR/# LOGICAL RECORDS 


44(2C) LASN (4) 


DATE FILE LAST ASSIGNED 


Figure 4-5 Primary Directory Entry 


Each directory entry is a 48-byte data structure that identifies 
and describes a file on the disk. Every file has an entry in the 
primary directory. As shown in Figure 4-5, the directory entry 
tells the file manager the: 


e Name and extension of the file 


e Low-order byte of the file's account number. (The eight bits 
of the high-order byte of the account number are distributed 
across the high-order bits of the eight characters of the 
filename. ) 


@ Addresses of the first and last sectors if the allocated file 
is a contiguous file, or the addresses of the first and last 
index blocks if the allocated file is a nonbuffered indexed, 
extendable contiguous, indexed or long record file 


e File's access privileges 
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@e Length of the file's records 


e File attributes or set of operations that can be performed on 
the file 


e® Date the file was allocated 
@ Date the file was last read or written by a task 


e Data block size and index block size if the file is an 
indexed, nonbuffered indexed, extendable contiguous or long 
record file 


@ Number of disk records or sectors currently used by the file 


Only one directory block can remain in =sememory at a time; 
therefore, only five file entries can be memory resident. The 
file manager scans these entries to find a file. To search the 
remaining files on the system, the file manager has to replace 
the primary directory block in memory with the next block from 
the disk. Examining five entries at a time to find a file can 
greatly increase the time it takes to access that file. 


To decrease the amount of time required to scan the directory, 
the file manager uses a secondary file directory. (See Figure 
4-6.) The secondary directory is a contiguous file named 
SYSTEM.DIR that is created when the disk is marked on-line with 
secondary directory support. The secondary directory points to 
each block of the primary directory and lists the filenames of 
the directory entries that are in each block. All or part of the 
secondary directory is maintained in memory in dynamic system 
space. 


After the file manager finds the filename it is searching for in 
the secondary directory, it can directly access the primary 
directory block that contains its directory entry. Note that 
while this method saves access time, the secondary directory does 
use more memory space than scanning the primary directory. 


To use the secondary file directory method, specify this option 
in the MARKON command when marking a disk on-line (see the 0S/32 


Operator Reference Manual). This command also allows the 
operator to specify the size of SYSTEM.DIR, including room for 
expansion. If, during processing, the secondary directory cannot 


accommodate any additional files that are being allocated, the 
disk must be marked off-line and then marked back on-line to 
recreate a larger secondary directory. The MARKON command will 
provide the operator with information to make a decision as to 
the preferred size of the secondary directory. 
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0(0) PRIMARY DIRECTORY BLOCK POINTER 1 [4] 


4(4) FILENAME 1 [12] 
16(10) FILENAME 2 [12] 
28(1C) FILENAME 3 [12] 
40(28) FILENAME 4 [12] 
52(34) FILENAME 5 [12] 

| 
| 
| 
| 
| 
eee Bee, Sd 
192(CO) PRIMARY DIRECTORY BLOCK POINTER 4 [4] 
196(C4) FILENAME 16 [12] 
208(DO) FILENAME 17 [12] 
220(DC) FILENAME 18 [12] 
232(E8) FILENAME 19 {12] 
244(F4) FILENAME 20 [12] 
256(100) 


Figure 4-6 Secondary File Directory (SYSTEM.DIR) 


Within a mirror disk environment, attention should be given to 
the file directories of the mirrored disks. Since the file 
directories are mirrored bit for bit on the secondary disk, the 
primary file directories must begin at the same position on both 
disks. If the secondary file directory SYSTEM.DIR is present in 
memory, it may need to be deleted and recreated for the primary 
disk if there are any defective sectors on the secondary disk. 
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4.8.2 Bit Map 


The file manager interrogates the bit map to determine which 
sectors are available for allocation. The bit map maintains an 
available space inventory for the disk volume. A bit in the bit 
map is assigned to each sector on disk. When a bit in the bit 
map is set to l, its corresponding sector is allocated for a 
file. When the bit is set to O, its corresponding sector is 
free. The disk initializer places the bit map close to the file 
directory to minimize disk head movement when allocating files. 


When marking on mirror disks, the bit map is used to’ synchronize 
the disks. If the disks are compatible, the primary disk's bit 
map is updated for all sectors that are defective on the 
secondary disk and for any extra sectors taken up by the 
secondary disk's pack administration Eile. The pack 
administration file (PACKINFO.DIR) is a file created and 
mainitained by the Fastchek Utility containing a list of 
Gefective sectors. Defective sectors are an important factor in 
establishing whether two disks can be mirrored. For further 
information regarding the pack administration file refer to the 
OS/32 Fastchek Reference Manual. 


4.8.3 Permanent and Temporary File Allocation 


When a file is allocated, it can be designated as a permanent or 


temporary file. If permanent, the file remains on disk until an 
operator command, MTM command or task asks the file manager to 
Gelete it. Temporary files remain on disk only as long as they 


are assigned to a task. Once the assignment to a task is closed, 
the file manager deletes the file. 


4.9 ASSIGNING FILES TO A TASK 


The OS/3Z file manager allows a task to access system resources 
via a logical unit (lu) number’ rather than by the name of a 
device or file. Up to 255 logical units (0 through 254) can be 
used by atask. Because 1u255 is reserved, it is not available 
for task use. 


All disk files that are to be accessed by a task must be assigned 
to an lu before any I/O operations can be performed to those 
files. Once a file is assigned to an lu, the OS/32 I/O subsystem 
ensures that the proper device driver or controller is used when 
the task requests an I/O transfer to the lu. Such I/0 requests 
are device-independent I/0; i.e., device assignments are made by 
the operator who started the task, not by the task that made the 
I/O request. 


For example, suppose a FORTRAN program has the following code: 


READ(2,100) A 
WRITE(1,100) B 
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When executed, the task reads a value from the device or file 
assigned to lu2, stores it into variable A, and writes the value 
of B to the device or file assigned to lul. The operator may 
assign lu2 to an MT terminal, disk file or whatever input device 
is available to the task. Likewise, lul can be assigned toa 
disk file, printer, terminal or whatever output device is 
available. Hence, device-independent I/0 allows the devices or 
files that will be used by a task to be changed without’ changing 
the’ actual code within the program. 


Sometimes a programmer may wish to perform an operation while 
suppressing the output from that operation. For example, one may 
wish to compile a program or build a task image without creating 
an object or task image file. To do this, the pertinent lu 
should be assigned to the NULL: device. This assignment allows 
the operation to be performed without generating any output from 
that operation. 


4.10 ACCESS METHODS 

The OS/32 system services that interpret and fulfill a task's 
request for storage and retrieval of data are known as access 
methods. The OS/32 I/O subsystem supports two access’ methods: 
buffered and nonbuffered. Both methods are transparent to the 
user. 

To perform a read or write operation, a task should have’ two 
interfaces to these access methods: 

e the user code interface that requests a data transfer (e.g., 


a READ or WRITE statement in FORTRAN), and 


e the lu assigned to the file required by the task. 
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RECORDS 


BUFFERED 


U-TASK RECORDS ACCESS 


METHODS 
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INDEXED, 
EXTENDABLE 
CONTIGUOUS, 
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RECORDS 


OR 
LONG RECORD 
FILE 

Figure 4-7 Task Interfaces to Access Methods 
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As shown in Figure 4-7, the access methods fall between these two 
interfaces. 


Each time a read or write operation is performed to a file, the 
access methods) adjust the current record pointer for that file. 
The value of the current record pointer is the number of a 
logical record in a file on disk. For contiguous and extendable 
contiguous files, this number refers to a logical sector address. 
For nonbuffered indexed, indexed files and long record files, 
this number refers to a logical record. The value of the current 
record pointer can range from 0 to the current number of records 
in the file minus one. 


All records can be accessed sequentially or randomly. When data 
records are transferred sequentially (i.e., one record at a time) 
the record pointer is automatically incremented by 1 to point to 
the next record after the last record or sector is transferred. 
After a random read or write operation is completed, the record 
pointer is set to the number of the record immediately following 
the last one that was transferred. 


In addition to read or write operations, the record pointer is 
adjusted whenever the following operations are requested by the 
task: 


e@ Rewind 


Record pointer is set to 0 


e Assign (open) 


Record pointer is set to O for all access’ privileges except 
write-only (SWO/EWO). If write-only is in effect, the record 
pointer is set to the number of the record following the last 
existing record in an indexed or nonbuffered indexed file and 
to the last record read or written in a contiguous or 
extendable contiguous file. 


@ Backspace Filemark (BFILE) 
If the file is a contiguous file, the record pointer is 
positioned to the number of the record containing a filemark. 
Otherwise, the record pointer is set to zero. 

e Forward Space Filemark (FFILE) 
If the file is a contiguous file, the record pointer 
backspaces to the number of the next record containing a 


filemark. Otherwise, the record pointer is set to the total 
number of records in the file. 
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@ Backspace Record (BREC) 
The record pointer is decremented by 1 unless it is already 
pointing to record number 0O. 

@ Forward Space Record (FREC) 
The record pointer is incremented by 1 unless incrementing by 


1 would cause the pointer to exceed end of file (EOF). 


Data can be transferred in either binary, image or ASCII mode. 
The amount of data that can be accessed is determined by the file 
type, as listed below. 


FILE TYPE BYTE-LIMIT PER TRANSFER 
Contiguous 2 to capacity of file 
Extendable contiguous 2 to capacity of file (Read) 

2 to capacity of disk (Write) 
Indexed 1 to record length 
Nonbuffered indexed 2 to record length 
Long Record 2 to record length 


4.10.1 Buffered Input/Output (1/0) (Indexed Files) 


Indexed files use buffered I/O. When a data block of an indexed 
file is read or written, the transfer occurs between the system 
buffer and the file. Data is moved between the system buffer and 
the user buffer as requested by the task. 


For example, to read data block 1 and data block 60, the data 
blocks are read into the system buffer before the records in the 
blocks are transferred to a user buffer. A data transfer is 
complete when one complete record has been moved into the user 
buffer or when the user buffer is full, whichever comes first. 
If a record does not fill the user's receiving buffer, the 
remaining bytes in the user buffer are unaffected. 


When a write operation is performed, data is moved from the user 
buffer to the system buffer before transfer to disk. The 
open-ended structure of the indexed file allows the file size to 
be extended during a write operation up to the available free 
space on the disk. However, file extension can only be performed 
sequentially; i.e., each record added to the file must follow the 
last record written to the file. Random write operations can 
only be performed to an existing record in the file. For 
example, if an indexed file consists of five records, a request 
to write record 6 causes the file size to be extended to a 
6-record length capacity. However, a request to write record 7 
or higher to an indexed file containing five records would return 
EOF status. 
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If a binary record written to an indexed file is shorter than the 
file's record length, the remaining bytes of the record are 
automatically filled with zeros. ASCII records that are shorter 
than the file's record length are padded with blanks. If a 
record longer than the files record length is read or written, 
the data exceeding the record length is not transferred. Hence, 
the record length of an indexed file should be large enough to 
hold the largest possible amount of data that will be read or 
written during one data transfer operation. 


4.10.2 Nonbuffered Input/Output (1/0) 


Nonbuffered I/O is used for contiguous, extendable contiguous, 
nonbuffered indexed and the long record file types. Data is 
transferred directly between the user buffer and the file on 
disk. All but contiguous files can be extended during write 
operations. Both random and sequential I/O are suppported by all 
four nonbuffered file types; however, some restrictions apply. 


With all nonbuffered I/O file types, transfer of data begins and 
ends on a sector boundary. Partially filled sectors are padded 
with the last two bytes of the transferred data. In addition, an 
even number of bytes should be transferred; otherwise, the 
processor hardware will add one additional undefined byte to the 
buffer. 


4.10.2.1 Accessing Contiguous Files 


Data records for a contiguous file are transferred in blocks 
greater or smaller than the file's record length (256 bytes or 
one sector). All transfers begin on a sector boundary and must 
be an even number of bytes. If the amount of data written to a 
file does not equal 256 bytes, the data is left-justified in the 
sector and the last two bytes of the data are propagated to the 
end of the sector. Because contiguous files cannot be extended 
during write operations, random writes can only be performed on 
existing allocated sectors. 


The EOF status for a contiguous file is returned as an end of 
medium (EOM), xX'90', marker. Pseudo filemarks, X'1313', are 
supported by contiguous files; the standard EOF, X'88', status is 
returned when a pseudo filemark is encountered. 


To extend the file length of a contiguous file, use OS/32 COPY to 


copy the file to another file of the desired size. See the 0S/32 
Copy User Guide for more information. 
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4.10.2.2 Accessing Nonbuffered Indexed Files 


Nonbuffered indexed files provide the flexibility of indexed 
files without the use of system space for data buffers or the use 
of processor time for moving data between system space and the 
task's I/O buffer. For example, suppose a nonbuffered indexed 
file is made up of a 250-sector data block consisting of 240-byte 
records. Since each record begins on a sector boundary, there 
will be 250 records in the block. Because the size of each 
record is less than 256 bytes, each sector is filled with the 
last two bytes of the data. To read records 15 and 62,015, data 
blocks 1 and 249 are accessed. If a 5-sector index block was 
specified, the addresses of both of these sectors would be in 
memory at the time of access when they would be transferred 
directly to the task's buffer. The time required to perform such 
a transfer is comparable to that required when using a contiguous 
file. 


Like indexed files, the open-ended structure of a nonbuffered 
indexed file allows the file to be extended sequentially during 
write operations. Random write operations can be performed on 
existing file records or on the next record after EOF. 


4.10.2.3 Accessing Extendable Contiguous Files 


A sector in an extendable contiguous file is directly accessed in 
the same manner as a contiguous file. Multiple data block 
transfer requests, however, require a separate I/O operation for 
each block. Contiguous files require one I/O operation for a 
multiple-sector transfer. As in contiguous files, the EOF status 
is returned as an EOM, X'90', marker. 


For example, suppose an extendable file has data blocks 
consisting of 250 sectors per data block. To read sector number 
15 and then sector number 62,015, simply access data blocks 1 and 
249. If the index block for this file is at least five sectors, 
the addresses of both blocks are in memory at the time of access 
and they are transferred directly to the task's buffer. The time 
required to perform such a transfer is comparable to that 
required by a contiguous file. 


Like nonbuffered indexed and indexed files, extendable contiguous 
files are open-ended. However, extendable contiguous files can 
be expanded sequentially and randomly. For example, a 10-sector 
file can be extended to a 20-sector file simply by writing to 


sector 20. The sectors between 10 and 20 are automatically 
allocated to the file. Essentially, for write operations no EOF 
exists. Hence, it is possible to fill a disk completely by 


writing to a sector with an unusually large random address. 
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4.10.2.4 Accessing Long Record Files 


In long record files, as in other nonbuffered I1/0 file types, 
data is transferred directly between the user's buffer in task 
space and the file on disk without incurring the overhead 
required by buffering in system space. The main difference 
between this file and other nonbuffered I/O types is that in a 
long record file, the data block size can be greater than 255 
sectors. In fact, the maximum size of a data block for a_ long 
record file can be up to 64K sectors. In accessing this file 
type, it must be remembered that the logical record length of the 
long record file is specified by its data block size. For 
example, if a long record file exists with data blocks of 4000 
sectors each, to read sector 6000, the user must access’ the 
second data block. Sector 6000 is in the second record of the 
file because the record length of the long record file is 
specified by the data block size. 


4.11 FILE SECURITY 

As explained in Chapter 2, a task cannot perform its function if 
the data it acts on has been destroyed. When data is contained 
in main memory, it is protected by the _ relocation/protection 
hardware. However, if task data is stored on disk, access to the 
files containing the data must be controlled. 

File access is controlled by matching a task with a set of 
permissible operations that they can perform on a given file. 
These operations are called access privileges. Access privileges 
are given to a task when a file is assigned to the task's lu. 
The access privileges are: 

@ Sharable Read-Only (SRO) 

@e Exclusive Read-Only (ERO) 

@e Sharable Write-Only (SWO) 

e Exclusive Write-Only (EWO) 

@e Sharable Read/Write (SRW) 

@ Sharable Read, Exclusive Write (SREW) 

@ Exclusive Read, Sharable Write (ERSW) 


@ Exclusive Read/Write (ERW) 
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When multiple tasks are assigned to the same file, the access 
privileges for those tasks should be compatible. For example, 
one task cannot have EWO privileges to a file while another’ task 
has SWO privileges. Table 4-1 shows which access privileges are 
compatible. If a file is assigned to a task with access 
privileges that are incompatible with those previously assigned 
for another task, the access privileges for the second assignment 
will automatically default to the previous assignment. 


TABLE 4-1 ACCESS PRIVILEGE 
COMPATIBILITY 
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If a file is assigned to multiple logical units for the same 
task, the file cannot be assigned for ERO on one lu and SRO on 
another. If a file is assigned for Exclusive Read or Write 
access on any given lu, the file cannot be assigned for that 
access on any other lu. 


A task can change its access privileges to a file without closing 
the file by requesting an access privilege change from the file 
manager. The new access’ privileges must be compatible with 
existing ones. 
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A file can also be protected from read or write operations 
through the read/write keys that are given to the file when it is 
allocated. See Table 4-2. The read/write keys can protect a 
file from being read from or written to by any task to which this 
file is assigned. For example, if a file's read and write keys 
are X'00' and X‘'0O7', respectively, the task to which this file is 
assigned can read from the file but it cannot write to it unless 
the file is assigned to the task with the same write key. 


TABLE 4-2 READ/WRITE KEYS 


KEY {| KEY ; MEAN ING 


00 Not protected 


FF Unconditionally protected, used 
by executive tasks; see the 
0S/32 System Level Programmer 
Reference Manual. 

07 00 Unprotected for read; condition- 
ally protected for write; task 
must match write key of X'07'. 


Unconditionally protected for 
write; conditionally protected 
for read; task must match the 
read key of X'A7'. 

00 


FF Unprotected for write; uncondi- 


tionally protected for read. 
27 32 Conditionally protected for both 
read and write; task must match 


both keys. 
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A task can change the keys of a file if the file has been 
assigned to the task with Exclusive Read or Exclusive Write 
privileges. For example, if the file is assigned to the task 
with the EWO privilege, the write key can be changed. If the 
file is assigned to the task with Exclusive Read/Write 
privileges, one or both keys can be changed. 
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Further protection is available when the disk is marked on-line. 
A a@isk volume can be marked on-line as write-protected. A 
write-protected volume will only accept assignments for SRO and 
SRW. (SRW is immediately changed to SRO.) No other access 
privileges are permitted. If the write-protected feature of the 
disk hardware is enabled, the volume should also be marked on as 
a protected volume. See the OS/32 Operator Reference Manual for 
more information on marking on a disk. 


4.12 CHOOSING THE RIGHT FILE TYPE 


Not every file type is right for every real-time application. 
Record length, access method and file expandability should all be 
taken into consideration when allocating and assigning files to 
a task. These and other file type characteristics are summarized 
in Table 4-3. The following sections describe the advantages and 
disadvantages of using each of the four file types, as well as 
some tips on handling disk fragmentation. 


TABLE 4-3 FILE TYPE SUMMARY 


a re ae ae ea a ee ne a me ee ee eee a ee ee ee ei a i oe i ee ee ew ee ee 
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4.12.1 Using Contiguous Files 


The primary advantage of using contiguous files is that all space 
required for the file is fixed when the file is allocated. Since 
the maximum file length cannot be changed, the user knows’ how 
much data can be input. This advantage should be weighed against 
the cost of losing file space when a _e contiguous file that 
contains a large number of unused sectors exists on disk. 
Contiguous files also support overlapped I/O and program 
execution. For all other file types, the task actually waits for 
an I/O operation to complete, even if an I/O proceed request was 
made. See the OS/32 Supervisor Call (SVC) Reference Manual for 
more information on I/O proceed requests. 


Another characteristic of contiguous files that proves helpful in 
some applications (e.g., magnetic tape emulation) is the ability 
to support filemarks. : 


Finally, . to achieve the fastest possible access time for 
applications that perform a large number of random read and write 
operations, use contiguous files. 


4.12.2 Using Indexed Files 

The advantage of using indexed files is that the user does not 
have to compute the size of the file before allocation. Hence, 
indexed files are best suited for applications where file size 


continues to expand throughout the life of the file. 


Many applications, such as compiling or assembling source code, 


are I/O bound; i.e., the time required to complete the job 
depends primarily on the speed of the sequential I/O to and from 
the disk. In these circumstances, indexed files with moderate 


block sizes provide the best throughput. Due to the additional 
central processing unit (CPU) overhead caused by buffering 
operations, using data block sizes of 5 to 20 sometimes causes a 
job to become cCPU-bound. However, many simple tasks do not 
become CPU-bound until much larger block sizes are used. 


It should be remembered that for strictly sequential access 
applications, nonbuffered indexed, extendable contiguous) and 
contiguous files all offer the same throughput, and all three are 
usually lower in performance than indexed files. 


The random access performance of indexed files depends on the 
correct choice of index and data block sizes. The optimal choice 
of data block size can usually be determined only by experiment 
for a particular application. In general, the index block size 
should be such that the file requires only one index block. (In 
reality, this is often not possible since the data blocks 
supported by indexed files are not as large as those supported by 
nonbuffered indexed and extendable contiguous files.) 
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4.12.3 Using Nonbuffered Indexed Files 


The purpose of nonbuffered files is two-fold. They provide the 
user with excellent random access performance for files of 
arbitrary logical record length, and they eliminate the CPU 
overhead and main memory requirements associated with buffered 
indexed files. 


For CPU-bound processes, or those processes that perform only 
random I/O on very large files of arbitrary record size, 
nonbuffered indexed files are preferred. Because these files 
have no data buffers in main memory, some users may prefer to use 
nonbuffered indexed files to conserve memory space, even at the 
expense of performance in typical sequential access operations. 


Like indexed files, the random access performance of nonbuffered 
indexed files also depends on the correct choice of index and 
Gata block sizes. Hence, the maximum possible data block size 
should always be used, unless disk fragmentation prevents such 
large block sizes. 


Nonbuffered indexed files are also suited for applications whose 
total file size continues to expand throughout the life of the 
file. 


4.12.4 Using Extendable Contiguous Files 


Extendable contiguous files provide all of the random access’) and 
performance advantages of contiguous files, without the drawback 
of fixed file sizes. Care should be taken, however, in choosing 
data and index block sizes to ensure the best possible 
performance. For example, suppose that an application requires 
a contiguous file of 200,000 sectors. Using the largest possible 
Gata block size (255 sectors), there would be 785 data blocks. 
These data blocks could be pointed to from one index block of 13 
sectors. Thus, for a cost of 13 sectors (3.25kb) of system 
space, the entire file index could be contained in memory. This 
would allow random access to the file to be the same as toa 
contiguous file. 


Extendable contiguous files are also suited for applications 


whose total file size continues to expand throughout the life of 
the file. | 
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4.12.5 Using Long Record Files 


Long record files provide the user with the unusual ability to 
read or write very long logical records to or from memory in a 


single I/O operation. This file type permits the user to 
transfer more than 255 sectors of data in one I/O operation, thus 
quickly freeing system resources for other purposes. If, for 


example, we had 200,000 sectors of data being input to the system 
and the I/O buffer size was 4000 sectors, the entire file could 
be written to disk in only 50 writes as compared with the 785 
writes needed for an extendable contiguous file of the same 
length. With a larger logical record length, even fewer writes 
would be necessary. 


The long record file type would be advantageous to a user _ who 
finds it necessary to transfer vast quantities of data more 
rapidly than is possible with the other file types. For example, 
such a user could establish several extremely large buffers in 
task space, and, in using the long record record file type, each 
buffer could be written to a disk in a single I/O operation. 


4.12.6 Disk Fragmentation 


The process of repeatedly allocating, expanding and deleting 
files of various sizes and record lengths eventually results in 
disk fragmentation. Here, fragmentation means that the available 
free space on the disk is divided among a great many relatively 
small areas. 


On the average, there are fewer places to allocate a large 
physical block than a small physical block. On badly fragmented 
disks, the maximum block size that can be allocated may be very 
small. Also, the time required to allocate any given block will 
increase with increasing block size Or increasing disk 
fragmentation, since there are generally fewer locations where 
the block will fit (that is, it takes somewhat longer to locate 
a large free space than it does a small free space). 


Disk fragmentation and total amount of free space both determine 
the maximum possible file size for any given physical block size. 
For example, on a given disk the maximum file size might be 
150,000 sectors if the block size were 5 sectors, but only 90,000 
sectors if the block size were 64 sectors, and only 40,000 
sectors if the block size were 250. On the same disk, the 
largest contiguous file that could be allocated would be 20,000 
sectors. 


Once a disk is badly fragmented, the only option available is to 


compress the disk. To compress a disk, initialize a new disk 
pack on another drive and copy all files from the fragmented pack 
to the newly initialized pack. If only a single drive is 


available (or no additional packs are available), the fragmented 
pack can be backed up to tape, reinitialized, then restored from 
the tape. 
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CHAPTER 5 
WRITING PROGRAMS THAT ACCESS OS/32 SYSTEM SERVICES 


5.1 INTRODUCTION 


The OS/32 supervisor calls (SVCs) provide the task interface to 
OS/32 system services. These calls activate the appropriate 
OS/32 executor routines that can handle the user's requests. For 
example, to request use of a system resource, a task issues an 
SVC7. To request transfer of information to the resource given 
to the task by SVC7, an SVCl is issued. 


When a task calls an executor routine through an SVC, the task 
must pass the information needed by the routine to perform the 
requested function. For example, to transfer data from a disk 
file, the operating system (OS) requires the address of the user 


buffer to which the data is to be sent. This information is 
passed through a special OS/32 data structure called the SVC 
parameter block. OS/32 provides a separate parameter block 


structure for each type of SVC that can be issued by the task. 
The task builds a parameter block in its task address space and 
stores the information required by the executor routine in that 
block. When the SVC is issued, the OS refers to data stored in 
the parameter block during execution of the routine. 


Perkin-Elmer provides a number of methods for writing application 
programs that access system services. A programmer working in 
OS/32 Common Assembly Language (CAL) can write a program that 
directly issues an SVC or executes an OS/32 system macro. library 
routine that issues an SVC. A FORTRAN program can issue an SVC 
by calling a Perkin-Elmer Run-Time Library (RTL) routine that 
issues the SVC. If a FORTRAN program is to access the file 
manager, the FORTRAN VII auxiliary input/output (1/0) statements 
can be used. Finally, a Pascal program can access system 
services through procedures contained in the standard Pascal 
Prefix supplied with the Perkin-Elmer Pascal compiler. These 
programming methods are outlined in Figure 5-1. 
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OS/32 
SYSTEM 
MACRO 


FORTRAN PASCAL 
STATEMENT PROCEDURE 


OS/32 
EXECUTOR 


Figure 5-1 Task Interface to OS/32 Executor Routines 


This chapter demonstrates how each of these methods is used to 
write a program that accesses two OS/32 system services; namely, 
the I/O and file management services. First, the SVCl and SVC7 
parameter block structures that pass data to the I/O and file 
management executor routines are discussed. See the 0S/32 
Supervisor Call (SVC) Reference Manual for more details on the 
individual parameters of the SVC parameter blocks discussed in 
these sections. 
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5.2 BUILDING A SUPERVISOR CALL (SVC) PARAMETER BLOCK 


The OS/32 macro library SYSSTRUC.MLB provides macro routines that 
define parameter blocks for SVCl, SVC5, SVC6, SVC7 and SVC13 in 
a task's address space. These macro routines are listed in the 
OS/32 Supervisor Call (SVC) Reference Manual. To build a 
parameter block structure within a task's address space, expand 
the appropriate OS/32 system macro routine and store the 
information required by the OS/32 executor routine in the 
parameter block. 


5.2.1 Accessing Input/Output (1/0) System Services 
To request an I/O service, the task first defines an SVC1l 


parameter block using the §$SVCl_ macro. $SVC1l defines the 
parameter block shown in Figure 5-2. 
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1(1) 2(2) DEVICE 3(3) DEVICE 
FUNCTION CODE LU INDEPENDENT STATUS DEPENDENT STATUS 
(SVC1.FUN) (SVC1.LU) (SVC1.STA) (SVC1.DN) 
BUFFER START ADDRESS 


(SVC1.SAD) 
BUFFER END ADDRESS 
(SVC1.EAD) 


RANDOM ADDRESS 
(SVC1.RAD) 


LENGTH OF DATA TRANSFER 
(SVC1.LXF) 


EXTENDED OPTIONS 
(SVC1.XOP) 


Figure 5-2 SVCl Parameter Block Defined by $SVC1l 
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Notice that the SVCl parameter block is divided into specific 
fields that contain the data required by the OS/32 I/O subsystem 
to perform the requested operation. The first field contains the 
function code indicating the particular I/0 function to be 
performed (see Table 5-1). For example, a parameter block for a 
read request contains the following: 


@e SV1.READ function code 

@e Logical unit (lu) assigned to the disk file to be read 

e Starting and ending addresses of the user buffer 

The following code builds an SVCl parameter block for an SVC1l 


that requests a data transfer from a file or device assigned to 
luli to the user buffer at location BUFF. 


Example: 
SVC1 DEFINE THE STRUCTURE 
ALIGN 4 
SVC.IN DS Svcl. ALLOCATE STORAGE FOR PARBLK 
ENDPBK EQU * 
ORG SVC1.IN+SVC1.FUN INITIALIZE FIELDS 
DB SV1.READ FUNCTION CODE 
DFB 1l LOGICAL UNIT=L 
ORG SVC1.IN+SVC1.SAD 
DC A( BUFF ) BUFFER START ADDRESS 
Dc A(BUFFE) BUFFER END ADDRESS 


ORG ENDPBK 


To request this operation, the task issues the SVCl as follows: 


svc 1,SVC.IN 


The following program uses SVCl to build two parameter blocks, 
one for an SVCl that performs a read operation from a file or 
device assigned to lul and one for an SVCl that performs a write 
operation to a file or device assigned to lu2. Notice that this 
program uses the function code SV1.WAIT to allow task execution 
to be suspended until each data transfer operation is complete. 
Also notice that the program checks the status field of the SVC1L 
parameter block to determine if the I/O operation was successful. 
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If the mirror disk option is selected and a primary read failure 
the 


occurred, 


device-dependent status. 


only. If 


receives a 0 in the device-independent status. 


the 


both primary and secondary disks. 


Example: 


SvCl 


SVC1.IN 
ENDPBK 


BUFF 
BUFFE 


SVC1.OUT 
ENDPBK 


START 


ERROR 


SIMPLE SVCl EXAMPLE 


8,9,10 


4 

SvCl. 

x 
SVC1.IN+SVC1.FUN 
SV1.READ!SV1.WAIT 
1 
SVC1.IN+SVC1.SAD 
A( BUFF ) 

A(BUFFE) 

ENDPBK 

80 

tial 

4 

SVCl. 

* 
SVC1.OUT+SVC1.FUN 
SV1.WRIT!SV1.WAIT 
2 
SVC1.OUT+SVC1.SAD 
A( BUFF ) 

A(BUFFE) 

ENDPBK 

* 


1,SVC1.IN 


0,SVC1.IN+SVC1.STA 


ERROR 
1,SVC1.OUT 


0,SVC1.OUT+SVC1.STA 


ERROR 
3,0 
* 


3,1 
START 


SVCl parameter block receives an X'86' in the 
Data is read to the secondary disk 
read was successful, the SVCl parameter block 


Data is 


DECLARE MACRO LIB TO CAL/MACRO 
DON'T LIST MACRO EXPANSIONS 


FREEZE LINE NUMBERS 
DEFINE SVCl STRUCTURE 
ALIGN PARBLK ON FULLWORD 
ALLOCATE INPUT PARBLK 


FUNCTION CODE=READ & WAIT 
LOGICAL UNIT=1 


BUFFER START ADDRESS 
BUFFER END ADDRESS 


ALLOCATE 80-BYTE BUFFER 


ALLOCATE OUTPUT PARBLK 


FUNC CODE=WRITE & WAIT 
LOGICAL UNIT=2 


SAME BUFFER AS INPUT 


ISSUE SVC1l TO READ LU1 
CHECK STATUS 

<0, ERROR 

ISSUE OUTPUT SVC TO LU2 
CHECK STATUS 

<0, ERROR 

NORMAL EOT=0 


EOT=1 
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read to 


5.2.2 Accessing File Management Services 


All file management requests are made through SVC7. For example, 
a task requests an lu assignment via the SVC7 assign function. 
The OS assigns the resource (file or device) to the requesting 
task's lu. The task proceeds to use it as required. When the 
task no longer needs the lu, the SVC7 close function is used to 
cancel the assignment. The SVC7 parameter block that passes’ the 
necessary information to the file manager is shown in Figure 5-3. 
To define this structure, use the $SVC7 macro. Notice that the 
SVC7 parameter block contains the file descriptor (fd) of the 
file on which the 0OS/32 executor is to perform the requested 
operation. 
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2(2) 
ERROR STATUS LU 
(SVC7.STA) (SVC7.LU) 


FUNCTION CODE 
$VC7.OPT) 


4(4) 5(5) 6(6) 


WRITE KEY 
(SVC7.WKY) 


READ KEY 
(SVC7.RKY) 


LOGICAL RECORD LENGTH 
(SVC7.LRC) 


VOLUME NAME OR DEVICE MNEMONIC 


(SVC7.VOL) 
FILENAME 
fetta (SVC7.FNM) 
20(14) 23(17) 
EXTENSION FILE CLASS/ 
(SVC7.EXT) ACCOUNT NO. 
(SVC7.ACT) 
24(18) 26(1A) ) 
INDEX BLOCK SIZE DATA BLOCK SIZE 
(SVC7.1SZ) (SVC7.DSZ) 


Figure 5-3 SVC7 Parameter Block Defined by $SVC7 


SVC2 code 16 can be used to pack an fd. into the SVC7 parameter 
block. This SVC must be used if the fd to be packed into the 
block specifies an account number. The parameter block for SVC2 
code 16 is shown in Figure 5-4. Note that there is no macro 
available for defining this structure. See the OS/32 Supervisor 
Call (SVC) Reference Manual for more information on coding the 
SVC2 code 16 parameter block. 
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0(0) 1(1) 2(2) 
OPTION CODE USER REGISTER 
4(4) 
ADDRESS OF PACKED FD AREA 


Figure 5-4 SVC2 Code 16 Parameter Block 


The following program issues an SVC7 and SVC2 code 16 to assign 
lu2 to a file named MYFILE.TXT/P.. The program uses §$SVC7 to 
define an SVC7 parameter block. A parameter block is also built 
for SVC2 code 16. This block contains the number of the register 
that holds the fd to be packed and the address of the SVC7 
parameter block field where the fd is to be packed. No error 
checking is performed by this program. 


Example: 
MLIBS 8,9 
PROG ASSIGN 
$SVC7 
ASSIGN DS SVC7. BUILD SVC7 PRBLK 


ASSIGNE EQU - 
ORG ASSIGN+SVC7 .OPT 
DC SV7 .ASGN!SV7 .SRW SET FUNCTION CODE & ACCESS PRIV 
ORG ASS IGN+SVC7 .LU 


DB X'2' INDICATE LU TO BE ASSIGNED 
ORG ASS IGNE 
ALIGN 4 
PACK EQU * BUILD SVC2,16 PRBLK 
DB X'10' SET DEFAULT VOLUME OPTION CODE 
DB 16 SET SVC CODE 
DC x'1' 
DC A(ASSIGN+SVC7.VOL) STORE ADR OF PACKED FD AREA 
ALIGN 4 
FD DB C'MYFILE.TXT/P' 
ALIGN 4 
START EQU x 
LA 1,FD LOAD FD INTO REG 1 


SVC 2,PACK 

svc 7,ASSIGN 

svc 3,0 END TASK WITH EOT O 
END START 
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The above examples represent only three of the I/O and file 
management services that can be accessed by an application 
program. For more information on other 0OS/32 system services, 
see the 0S/32 Supervisor Call (SVC) Reference Manual. 


5.3 USING THE OS/32 SYSTEM MACRO LIBRARY TO ACCESS SYSTEM 
SERVICES 


The OS/32 system macro library provides macro routines that not 
only build an SVC parameter block but also issue the SVC for a 
task. The programmer simply provides the necessary data for the 
OS/32 executor as operands to the macro instruction that expands 
the routine. For example, to output data from the user buffer, 
BUFF, to the file or device assigned to lu2, execute the WRITE 
macro instruction as follows: 


WRITE LU=2,ADDR=BUFF , REGL=80 , ENDADDR=BUFFE 


The WRITE macro routine builds an SVCl parameter block with the 
SV1.WRIT function code set. Using the operands specified in the 
macro instruction, the WRITE routine stores the values’ for lu, 
record length (REGL) and the user buffer's starting and ending 
address in the appropriate fields of the SVCl parameter block. 
The routine then issues SVCl. 


The following assembly program uses system macros to access’ the 
read, write, assign and allocate OS/32 executor routines. 


Example: 
PROG SVC1l AND SVC7 MACRO EXAMPLE 
MLIBS 8,9,10 
BUFF DS 80 
BUFFE EQU *-1 
START EQU x 


ALAS FD='TEST2.DTA' ,LU=2,AP=SRW, RECL=80,FT=IN, BLKSI ZE=1,NDXSIZE=1 
ASSIGN LU=1,FD='CARDIN.FMU/S' 
READ LU=1,ADDR=BUFF , RECL=80 , ENDADDR=BUFFE 
WRITE LU=2,ADDR=BUFF , RECL=80 , ENDADDR=BUFFE 
EOT RC=0 
ENID START 


In the above example, the ALAS macro routine builds an SVC7 
parameter block and then issues an SVC7 to allocate the file 
TEST2.DTA and assign the file to lu2. The ASSIGN macro routine 
builds another SVC7 parameter block and issues an SVC7 to assign 
CARDIN.FMU/S to lul. 


48-039 FOO RO2 5-9 


The READ macro routine builds an SVCl parameter block and issues 
an SVCl to read data from CARDIN.FMU/S into the user buffer at 
location BUFF. The WRITE macro routine builds an SVCl parameter 
block and issues an SVCl to write data from BUFF to the indexed 
file TEST2.DTA. 


See the 0S/32 System Macro Library Reference Manual for details 
on how to use the 0OS/32 macro routines for writing assembler 
language programs that access OS/32 system services. 


5.4 WRITING A FORTRAN PROGRAM THAT ACCESSES SYSTEM SERVICES 


The Perkin-Elmer FORTRAN VII RTL provides subroutines that allow 
access to system services through a FORTRAN application program. 
Like the OS/32 system macro library routines, these subroutines 
build the SVC parameter block and issue the SVC for the program. 
The programmer simply calls the RTL routine specifying the 
required SVC parameters as arguments to the call. For example, 
the SYSIO RTL routine is used to access OS/32 I/0 services. 
SYSIO builds an SVCl parameter block using the arguments in the 
CALL SYSIO statement. After the block is built, SYSIO issues an 
SVCl to perform the requested I/O operation. 


The following example uses SYSIO to transfer data from the disk 
file assigned to 1lu2 to the user buffer at location BUFF. A 
second RTL subroutine, IOERR, is called to interpret the _ status 
of the I/O request after the operation is completed. IOERR 
places the status code contained in the error status field of the 
SVCl parameter block into the argument ISTATUS and outputs a 
message to the device assigned to lu6. 


Example: 


INTEGER LU, ISTATUS,NBYTES , RANADD, FC 
INTEGER PBLK(5), BUFF(20) 

LU=2 

NBYTES=80 

RANADD=0 

ISTATUS=0 

FC=Y¥'28' ; SVC1l READ WAIT FUNCTION CODE 
CALL SYSIO(PBLK,FC,LU,BUFF ,NBYTES , RANADD) 
CALL IOERR(PBLK, ISTATUS ) 

IF (ISTATUS.NE.0) GO TO 10 
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Where: 


PBLK specifies the array in which the parameter 
block will be built. 

BUFF is the buffer array that is to be output. 

LU is the logical unit assigned to the output 
device. 

NBYTES specifies the number of bytes that will be 
output. 

Y'26! is the function code telling the 0OS/32 


executor to perform the write operation and 
suspend task execution until data transfer is 
completed. 


See the FORTRAN VII User Guide for more information on using the 
RTL routines to access system services. 


To access file management services, the Perkin-Elmer FORTRAN VII 
compilers provide auxiliary I/O statements; e.g., OPEN and CLOSE. 
These statements are similar to the system macro library and RTL 
routines in that they build the necessary parameter block and 
call the SVC. These statements include parameters required to 
perform the specific file management function. 


Example: 
OPEN (UNIT=1,FILE='CARDIN.FMU/S' ,STATUS='OLD' , ERR=100) 


The above example assigns the file CARDIN.FMU/S to lul by 
building an SVC7 parameter block and issuing an SVC7 to assign 
the file. STATUS=OLD tells the OS that the file has already been 
allocated. If the file assignment operation ends in error, the 
program branches to statement label 100. 


See the FORTRAN VII Reference Manual for more information on the 
use of auxiliary I/O statements. 


5.5 WRITING A PASCAL PROGRAM THAT ACCESSES SYSTEM SERVICES 


The standard Pascal Prefix supplied with the Perkin-Elmer Pascal 
package contains CONST, TYPE and PROCEDURE declarations that can 
be used to access system services. The Prefix also supplies 
procedures that provide access to system or SVC services. Like 
the FORTRAN VII standard RTL routines, these Pascal procedures 
both build the SVC parameter block and issue the SVC. The data 
required by the OS/32 executor is passed via the procedure 
parameters as shown in the following example. 
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Example: 


(*$ INCLUDE (PREF IX.PAS/S)*) 
PROGRAM SAMPLEPAS (OUTPUT) 


VAR STATUS: BYTE; 


BEGIN 
OPEN(1, 'M300:CMDBbybs.FIL/P',SRW,0,STATUS) ; 
IF STATUS< >0 THEN 

WRITELN (‘ERROR STATUS=',STATUS); 

END 


The above procedure uses the OPEN Prefix procedure to assign the 
file M300:CMD.FIL/P to lul. With the OPEN procedure, an SVC7 
parameter block is built and an SVC7 is issued to assign the lu. 
This program checks the status field returned by the OPEN 
procedure. This status is the SVC7 parameter block status after 
the I/O operation is completed. If an error has occurred, this 
program outputs an error message. 


See the 0OS/32 Pascal User Guide, Language Reference and Run-Time 


Support Reference Manual for details on how to use the Pascal 
Prefix to write a Pascal program that accesses system services. 
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Directory block 
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i 4-14 
Access methods i Disk 
buffered 4-17 |} compress 4-28 
4-20 | drives 4-2 
nonbuf fered 4-17 |} failure 4-9 
4-20 } file management services 4-1 
- Access privileges 4-22 |} formatting 4-3 
AF CONT 3-6 i fragmentation 4-28 
AF PAUSE 3-6 H marking on 4-14 
APU 3-21 | 4-25 
3-33 } space management 4-10 
task queue entry 3-25 {| Disk file types. See File 
Arithmetic fault i types. 
error messages 3-7 i Disk organization 
Assigning files 4-16 | control information 4-6 
Authorized User Utility 1-5 i user-defined data 4-6 
Auxiliary processing unit. i Dynamic system space 4-8 
See APU. i 
1 
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B i 
: End of file 4-21 
Bit map 4-6 i End of medium 4-21 
4-16 { Environment 
{ mirror disk 4-9 
1 4-15 
Cc H real-time 1-3 
i 3-1 
CAL 5-1 H 4-7 
Central processing unit. H real-time. i=l 
See CPU. H time-sharing 1-1 
CLOSE 5=12:-:] 1-4 
Code } 2-12 
impure © 2-2 i Executor routines 
pure 2-4 H file management 5-2 
Common assembly language. H sample program 5-10 
See CAL. H task interface to 5-1 
Contiguous files 4-6 | Extendable contiguous files 4-8 
4-7 H 4-19 
4-19 } accessing 4-21 
accessing 4-21 |} using 4-27 
using 4-26 } 
CPU 1-4 H 
3-21 | F,G 
3-33 | 
4-26 {; Faults 
bound processor 4-27 |} arithmetic 3-5 
CTOP 2-7 H 3-7 
i 3-16 
H data format/alignment 3-5 
D H 3-16 
H illegal instruction 3-5 
Data block 4-5 H 3-16 
4-27 } memory access 3-5 
buffers 4-8 H 3-16 
DEBUG /32 2-4 H power restoration 325 
Device H 3-16 
driver 4-2 i fd 4-2 
trap-generating 3-32 { 
,] 
' 
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File H 
directories 4-6 
4-12 History records one 
security 4-22 
support services 4-1 
File allocation I,J,K 
permanent 4-16 
temporary 4-16 1/0 ~ 


ios] 


File descriptor. See fd. 

File management services 
accessing 

File manager 


accessing system services 
device-dependent 
device- independent 


on 


performance 
queuing of requests 
Image file 
format 
Index block 
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Linked-list organization 

Loader information block. 
See LIB. 

Loc 3-1 


long record 


Location counter. See LOC. 
Logical unit. See lu. 
Long record files 4-9 


nonbuffered indexed 


accessing 4-22 
using 4-28 
lu 2-11 
4-16 

assignment 5-7 


Filemark 


pseudo 
Files 


M 


assigning 
FORTRAN 


MAC 2-5 
MARKON command 4-14 
MAT 2-§ 
Memory access controller. 

See MAC. 
Memory address translator. 

See MAT. 
Memory addressing 1-3 


RTL 
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sample program 5-11 
trap-handling programs 3-35 
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Mirror disk 


Q 


Queue message service 


environment 


marking on R 


Monitor 


Random access 


WO > wun 


WN ee Bm Oe 
NEP RE RPOMw A 


Monitor tasks. See Monitor. 
MTM 


READ macro 
Read/write keys 
Real-time environment 


mein areas 
OO be a 
ht 


Authorized User Utility 
command language 


Multitasking system. See 
Environment, real-time. 


N 
NAF PAUSE 
Nonbuffered indexed files 
accessing 
using 


NULL: device 


RTL 


Run-time library. See RTL. 


Ss 


Secondary file directory 
Segmented task 


root segment 


n 
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iipid 
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O Sequential access 
ODT = Spoolers . 
OPEN -13 OS /32 
Operating system. See OS. SPL/32 
OPTION WORK command = Spooling utilities 
os = Storage devices 
- secondary 
Subtask 


Overlay descriptor table. 
See ODT. 


P 


Pack administration file 
Partial image 
PASCAL 
sample program 
trap-handling programs 
Primary directory entry 
Priority scheduling 
mechanism. See PSM. 
Private image 
Program status word. See 
PSW. 
PSM 
PSW 
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reason codes 


Supervisor call. See SVC. 


SVC 


parameter block 


SVC13 
Svc5 
SVC6 

svcl 
and mirror disks 
function codes 
parameter block 


sample call 
sample parameter block 
SVC14 


SVC2 
code 16 
sample program 
SVC6 
SVC7 
$SVC7 macro 
parameter block 
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SVC7 (Continued) Task trap-handling routines 


i] 
i] 
sample program 5-9 { writing 3-31 
with SVC2 5-8 { Task traps 3-1 
Svc9 3-12 | 3-13 
3-18 | 3-26 
SYSSTRUC.MLB. See system H sample program 3-27 
macro library. | TCB 2-4 
System H 3-2 
resource management 4-2 i 3-16 
space 4-21 ; Time-sharing 
System macro library 3-27 | environment L=1 
5-3 i 1-4 
5-9 | 2-12 
sample program 3-35 { Time-slicing 1-4 
use of 3-35 |; Timer facility 1-3 
System macros } Trap-generating devices 3-32 
sample program 5-10 ; Trap-handling programs 3-33 
System services } 3-35 
access 2-13 |} 3-36 
5-1 H example of 3-34 
5-9 i ; 3-36 
5-10 jj; 3-37 
5-12 {| Trap-handling routines 1-3 
System space 2-4 i} Traps 3-5 
i 3-38 
H arithmetic fault 3-17 
a H asynchronous software 
H events 3-16 
Task ! data format/alignment 
address space 2-5 H faults 3-18 
interrupts 2-4 { handled by u-tasks 3-16 
nonresident 2-9 { hardware-based events 3-16 
ODT 2-4 H illegal instruction 
over lay 2-4 i faults 3-19 
2-7 i memory access faults 3-19 
priorities 1-3 H 3-38 
2-9 H power restoration 3-19 
queue entries 2-4 H synchronous software 
3-24 | events 3-16 
queue traps 3-30 j; user-defined 3-17 
resident 2-9 H 
scheduler 2-9 i 
structure 2-1 | TSW 2-4 
3-28 | 3-1 
Task control block. See TCB. { 3-2 
Task image 2-1 { 3-16 
2-2 H 3-17 
OPTION command 2-2 H 3-20 
Task queue H 3-27 
service 3-20 } 3-30 
service events 3-16 } bit settings 3-3 
service routine 3-16 } task-initialized 3-12 
trap-causing events 3-20 } UDL swap 3-9 
3-22 } 
3-26 | 
Task queue traps H U 
sample program 3-31. | 
Task states } U-task 
current 2-9 H loading 2-5 
dormant 2-9 { UBOT 2-7 
ready 2-9 | UDL 2-4 
rolled 2-9 H 2-7 
wait 2-9 | 3-1 
2-10 } 3-16 
Task status word. See TSW. H 3-27 
H building a 3-30 


IND~-4 48-039 FOO RO2 


UDL (Continued) 
fields 
TSW swap 
User-dedicated location. 
See UDL. 
User task. See u-task. 


Vv 


Virtual task master. See 
VIM. 
Volume descriptor 


VTM 


W,X,Y,2 


WRITE macro 
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